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

[olsalas711]

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:

• One GitHub repository (e.g., https://github.com/org/project-storefront)
• Several branches (main, pre-launch, dev)
• Different custom domains that need to be assigned to each environment (e.g., www.site.com, stg.site.com, dev.site.com)

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!

[SantoshSai]

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/gi...

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

Hope that helps!

[olsalas711]

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]

@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/)

How to reflect branch-specific behaviour

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

[olsalas711]

Hi @SantoshSai , thanks so much for the detailed clarification — this really helps!

I’d like to follow up on the Cloud Manager API part, specifically regarding the branchName parameter.

Cloud Manager API Spec

While reviewing the API documentation, I noticed that there’s no concrete example payload or list of accepted properties for creating or updating an Edge Delivery site.

Would it be possible for you to:

Confirm the exact payload structure required to create or update a site with a different branchName?

Point me to any official documentation or working example where the full payload schema is described?

I’d like to automate site setup for multiple environments (dev, staging, prod) from the same repo and need to ensure I’m using the correct format.

Thanks again for your guidance — really appreciate your time!

[AmitVishwakarma]

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

[olsalas711 · Accepted solution]

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/usi...