How to configure multiple Edge Delivery sites from different branches of the same GitHub repository with custom domains? | Community
Skip to main content
O
olsalas711
Level 4
May 9, 2025
Solved

How to configure multiple Edge Delivery sites from different branches of the same GitHub repository with custom domains?

  • May 9, 2025
  • 1 reply
  • 1441 views

Hi everyone,

 

I'm currently working with Adobe Edge Delivery Services and I have a question regarding site configuration using multiple branches from the same GitHub repository.

 

We have the following setup:

 

Our goal is to:

 

Create a separate Edge Delivery site for each branch and associate a different custom domain with each site.

 

However, when creating a new site in Cloud Manager, it seems the tool automatically links to the main branch, and we don’t see any UI option to specify another branch. As a result, even with different GitHub repositories or site names, the preview and production URLs resolve to the same main--repo--org.hlx.page endpoint.

 

My questions:

 

  • Is there a way to explicitly select the branch when creating an Edge Delivery site in Cloud Manager?
  • If not, what is the correct way to manage multiple environments (dev, staging, production) with custom domains, all coming from branches of the same repo?
  • Are there any YAML or configuration-level options that can be used to force the branch reference?

Any official guidance or examples would be greatly appreciated.

Thanks!

Best answer by olsalas711

Hi @olsalas711 ,

Try below solution:

1. Create Edge Delivery Sites via API with branchName

Adobe Cloud Manager API supports setting a different branch via the branchName property in the site creation payload.

First, authenticate:

Use Adobe I/O or JWT credentials to get an access token:

curl -X POST https://ims-na1.adobelogin.com/ims/exchange/jwt \ -F 'client_id=YOUR_CLIENT_ID' \ -F 'client_secret=YOUR_CLIENT_SECRET' \ -F 'jwt_token=YOUR_JWT' \ -F 'grant_type=client_credentials'

2. Payload Structure for Creating an Edge Delivery Site

Here’s the exact API payload you can use to create a new site with a specific branch:

{ "name": "my-dev-site", "repository": { "url": "https://github.com/org/project-storefront", "branchName": "dev" }, "domains": [ { "domain": "dev.site.com", "type": "live" } ], "siteType": "EDS" }

Repeat this for other environments with the appropriate branchName and domain.

 

3. API Endpoint

POST https://cloudmanager.adobe.io/api/programs/{programId}/sites

Use appropriate headers:

Authorization: Bearer {access_token} x-api-key: {your_api_key} x-gw-ims-org-id: {your_org_id} Content-Type: application/json

4. Update an Existing Site (Optional)

To update the branch of an existing site:

PATCH https://cloudmanager.adobe.io/api/programs/{programId}/sites/{siteId}

Payload:

{ "repository": { "branchName": "staging" } }

Repo Structure:

Make sure each branch includes these files tailored to the environment:

project-storefront/ ├── helix-config.yaml ==> domain/mount config (per branch) ├── fstab.yaml ==> external content mapping ├── .github/workflows/deploy.yaml ├── layouts/ ├── scripts/ └── index.md

Each branch should have its own version of helix-config.yaml pointing to its environment’s domain.

Domain Mapping

After creating the site, go to the Cloud Manager UI => Your Site => Custom Domains, and confirm the correct *.site.com mapping.

Regards,
Amit


Hi @amitvishwakarma ,

 

I was able to achieve it using the following payload:

{ "siteName": "<siteName>", "branchName": "<branch>", "repo": "<repo>" }

 In the response JSON, I could see the origin field correctly populated as:

"origin": "<branch>--<repo>--<owner>.aem.live"

 

Following the instructions in: 

 https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/using-cloud-manager/edge-delivery-sites/manage-edge-delivery-sites#manage-an-edge-delivery-site-between-helix-4-and-helix-5 

1 reply

SantoshSai
Community Advisor
SantoshSaiCommunity Advisor
Community Advisor
May 10, 2025

Hi @olsalas711,

1. Can you explicitly select the branch when creating an Edge Delivery site in Cloud Manager?

Currently, no - Adobe's EDS Cloud Manager UI does not provide an option to choose a different branch during site creation. By default, it uses the main branch of the linked repository.

2. What's the correct way to manage multiple environments with custom domains from the same repo?

To achieve multiple environments (dev, stage, prod) with distinct custom domains and branches, Adobe recommends using multiple GitHub integrations, even if they point to the same repo but with different branch targeting. Here's how to do it:

Recommended setup:

  1. Create multiple GitHub integrations (each with a unique label like "EDS Dev", "EDS Staging", etc.).

  2. Manually edit the integration's helix-config.yaml (or fstab.yaml) in each branch to reflect:

    • The correct mountpoints

    • Environment-specific configurations

  3. In each branch, point the configuration to a different domain (via host settings).

  4. Create a site per environment, each mapped to a different GitHub integration (even if it's the same repo).

This simulates "multi-branch" behavior because each site will clone and deploy the branch associated with the GitHub integration.

3. Any YAML or config-level option to force the branch?

Not directly in YAML like fstab.yaml or helix-config.yaml, but:

  • Adobe does clone the branch associated with the GitHub integration.

  • You control branch-specific behavior by:

    • Branch-specific code/content

    • Branch-specific YAML (like fstab.yaml)

    • Defining mountpoints, directoryIndexes, and even prod/staging domains inside those files

So while there’s no branch: key to set in the YAML, the branch context is honored at the GitHub integration level.

4. Practical Example:

Let’s say:

  • main = prod (→ www.site.com)

  • pre-launch = staging (→ stg.site.com)

  • dev = dev (→ dev.site.com)

Steps:

  1. Create three GitHub integrations, each pointing to:

    • main

    • pre-launch

    • dev

  2. Create three Edge Delivery sites:

    • Site A: Production (link to main)

    • Site B: Staging (link to pre-launch)

    • Site C: Dev (link to dev)

  3. Configure custom domains in each site's deployment settings.

  4. Modify each branch’s fstab.yaml and helix-config.yaml if needed.

References: https://github.com/adobe/helix-shared/blob/main/CONFIGURATION.md

https://experienceleague.adobe.com/en/docs/experience-manager-cloud-manager/content/managing-code/git-integration

https://www.aem.live/developer/anatomy-of-a-project

 

Hope that helps!

Santosh Sai
    O
    olsalas711Author
    Level 4
    May 10, 2025

    Hi @santoshsai , thank you for the detailed response!

     

    Just to make sure I fully understand the suggested approach:

     

    When you mention “create multiple GitHub integrations,” are you referring to:

     

    • Creating separate GitHub repositories per environment (e.g., one repo per branch)?
    • Or using the same GitHub repository, but configuring different integrations within Cloud Manager, each tied to a specific branch?

    If it’s the second option (same repo, multiple integrations), I would really appreciate more clarity on where/how those GitHub integrations are defined and managed, since the UI only lets me connect a repo once (as far as I can see).

     

    Also, regarding the boilerplate (Edge Delivery Services template):

     

    Could you please guide me on:

    • Which configuration files are key (e.g., fstab.yaml, helix-config.yaml, etc.)
    • Where exactly are they located in the typical EDS repo structure?
    • And how I can adapt them to reflect branch-specific behavior or domain mappings?

    Thanks again for your help—this is incredibly useful as we structure multi-environment support for a shared EDS codebase.

     

    SantoshSai
    Community Advisor
    SantoshSaiCommunity Advisor
    Community Advisor
    May 10, 2025

    @olsalas711 

    1. Multiple GitHub integrations: repo vs branch

    When we say “multiple GitHub integrations”, we are not recommending multiple repos per environment unless necessary. Instead:

    Correct approach:

    Use one GitHub repository, with separate branches (e.g., main, dev, staging), and create separate Edge Delivery Sites for each environment in Cloud Manager, each pointing to a specific branch.

    Problem:

    Yes, you're right - the UI currently only allows linking to one branch (main) when you create a site. But...

    Workaround (via API):

    You can use the Adobe Cloud Manager API to create or update an Edge Delivery Site and specify a different branch using the branchName parameter.

    Cloud Manager API Documentation


    2. Where/How are GitHub integrations defined?

    In Cloud Manager, you define the GitHub integration once for your program (via the Admin Console or onboarding flow). However:

    • Each Edge Delivery Site you create (via API) can point to:

      • The same GitHub repo

      • But a different branch

    This is how you achieve a multi-environment setup (dev, staging, prod) with one repo but separate deployments.


    3. Key configuration files in Edge Delivery Services (EDS)

    Here’s what’s important and where it lives in the repo:

    File Purpose Location
    helix-config.yaml Main config file — defines mountpoints, directory index, edge logic Root of repo
    fstab.yaml Defines external content sources (e.g., SharePoint, Google Drive) Root of repo
    .github/workflows/*.yaml CI/CD workflows using GitHub Actions .github/workflows/
    config.prod.yaml, config.stage.yaml (optional custom) You can create custom environment-specific YAMLs and import them conditionally via code Wherever your logic supports it (root or /scripts/)

    There are three ways to reflect different behaviour per branch/environment:

    1. Branch-specific Logic in Code
      Use environment variables (e.g., HLX_ENV, or set via GitHub Actions or Cloud Manager) to dynamically load configuration files based on branch.

    2. Different Configuration per Branch

      • Have different versions of helix-config.yaml, fstab.yaml, etc. in each branch.

      • Example: main branch has helix-config.yaml pointing to www.site.com

      • dev branch has helix-config.yaml pointing to dev.site.com

    3. Custom Domain Mapping
      In Cloud Manager, assign a custom domain to each Edge Delivery Site (via UI/API), regardless of the branch name.

    Folder Structure of a Typical EDS Repo

    your-eds-repo/
├── fstab.yaml
├── helix-config.yaml
├── index.md
├── .github/
│   └── workflows/
│       └── deploy.yaml
├── layouts/
│   └── default.plain.html
└── scripts/
    └── index.js

     

    Santosh Sai
      Terms & ConditionsAccessibility statement

      Loading footer...