style
content

Bring Your Own Git

Edge Delivery Services recommends using GitHub or GitHub Enterprise Cloud to host and deploy project code for frictionless adoption and seamless integration. If you are already an AEM customer and your organization is unable to use GitHub for the source code, you can now use Cloud Manager as an intermediary and configure your own git based repository service there.

The following git based repository vendors are currently supported via Cloud Manager:

We’re currently supporting additional vendors in an Alpha phase. To enable support for them, contact us at cloudmanager_byog@adobe.com

Note: Edge Delivery Services expects a main branch to be present in your repository for production code.

1. Prepare your Edge Delivery Services Site

Before you can configure your external repository, you need to have an aem.live org registered in the configuration service and have an admin user who can perform updates to the site configuration. An easy way to get started is to follow the developer tutorial. Once your site is up and running, contact an Adobe representative to create the aem.live org for you and add the administrative user(s).

Please note: even if you don’t use github.com as the source repository, the name of the aem.live org still needs to exist as a github.com org controlled by you. This ensures that nobody can (ab)use the same organization name.

2. Configure your External Repository in Cloud Manager

As a first step, configure your external repository in Cloud Manager. If you are new to AEM, see here for an introduction and to find out how to access Cloud Manager.

Once the repository ownership is confirmed and the status is set to ready, you will need to set up a webhook for your git repository. This will allow Cloud Manager to receive push event notifications whenever changes are made to your repository. You can find the webhook details in Cloud Manager, and they are unique for each repository.

The webhook requires an API key, which is the same key used for interacting with any Cloud Manager API. For more details on generating the Cloud Manager public API key, refer to the public documentation. Additionally, a webhook secret must be configured in your git vendor solution when creating the webhook. This secret will be used to sign each event sent to Cloud Manager.

If your git repository is not publicly accessible, you can request a list of IPs used by Cloud Manager. To do this, send an email to cloudmanager_byog@adobe.com from the email address associated with your Adobe ID. Be sure to specify which Git platform you want to use and whether you are using a private, public, or enterprise repository structure.

3. Configure your Edge Delivery Site in Cloud Manager

Once you have your aem.live site, you need to onboard it into Cloud Manager and validate its ownership. For more details, please refer to the Cloud Manager public documentation.

Once you select the "Bring your own Git" option, a pop-up window will appear prompting you to choose the repository you wish to use as the source code for the site.

Once the repository is selected, Cloud Manager will provide a secret that must be added in your site configuration. Be sure to copy the secret and store it securely, as it won't be visible again in Cloud Manager. If you reconfigure the site, Cloud Manager will generate a new secret.

4. Configure your AEM Site to use Cloud Manager

Next, you need to add the code repository to your site configuration. If you are new to Edge Delivery Services, it is recommended that you familiarize yourself with the Admin API.

curl -v -X POST https://admin.hlx.page/config/<org>/sites/<site>/code.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: <your-auth-token>' \
  --data '{
    "source": {
      "url": "https://cm-repo.adobe.io/api",
      "raw_url": "https://cm-repo.adobe.io/api/raw",
      "owner": "<program-id>",
      "repo": "<repository-id>",
      "type": "byogit",
      "secretId": "cm-byog"
    }
  }'

You will need to replace <org> and <site> with your actual values from the configuration service, and <program-id> and <repository-id> with the actual values from Cloud Manager. The latter details can be easily found in the “Configure Webhook” section of the repository.

You also need to create a secret named "cm-byog" using the Admin API. The value of this secret should be the one provided by Cloud Manager in the previous step.

curl -v -X POST https://admin.hlx.page/config/<org>/sites/<site>/secrets/cm-byog.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: <your-auth-token>' \
  --data '{
    "value": "<secret from cloud manager>"
  }'

5. Trigger your first sync

In Cloud Manager, select the "Sync Code" option from your site's dropdown menu.

In the popup that appears, choose the branch you wish to sync.

This action will update your Edge Delivery Site with the code from your private git repository and the selected branch. For more details about the sync jobs, you can use the following Admin API.

curl -X GET https://admin.hlx.page/job/<org>/<site>/<branch>/code \
  -H 'content-type: application/json' \
  -H 'x-auth-token: <your-auth-token>'

6. Verify your AEM Site

Browse your site at https://main–{site}--{org}.aem.page
to ensure the initial synchronization from your external repository has worked as expected.

To test continuous code synchronization, make a change to one of your code files (ideally something easy to spot in the browser) and push it to the main branch of your external repository and ensure the change is reflected on your AEM Site.

Note: Code synchronization happens asynchronously and your changes may not be reflected immediately. Disable your browser cache or use an incognito window for testing to circumvent your browser’s cache and force it to fetch all resources from the server.