Introduction

Layered modules are designed to allow teams to update and deploy the same metadata across multiple production orgs

This allows a central team to deploy business wide updates without interrupting the development taking place in the individual orgs.
This is commonly used in cases where a business has a central team that maintains multiple region specific organisations.

Building a Pipeline with layered modules allows teams to layer their shared and org specific metadata together in an easy to understand UI.

Before you start

1. Make sure that you have connected all of your orgs to Gearset. You should connect to these orgs using team-shared connections. Give your orgs "friendly names" so that it's easy to identify their purpose.

You should have:

at least 2 Production orgs (team-shared)
at least 2 UAT sandboxes (team-shared)
at least 2 development sandboxes (user owned/team-shared)

Once your orgs are connected the team-shared connections page should look something like this:

2. Next step is to make sure that all of your ongoing work in your repository is resolved.

Resolve any ongoing work
Close/merge the open feature branches
Merge all environment branches so only main is left
Important: Create a new branch (a copy) from main, to create a snapshot of the main branch and to act as a backup.

Restructuring your repository

Navigate to your existing repository on your source control provider.

On your main branch, click Add file and create a .json file named gearset-multiregion.json

The content of the .json file should be as follows

{
    "overlays": {
        "Org 1": ["core", "org 1"],
        "Org 2": ["core", "org 2"],
        "core": ["core"]
    }
}

Replace the values "Org 1" and "Org 2" with the friendly names of your Production orgs (in this example I'm using "NA" for my North America org, and "EU" for my European org).

The end result should be something like this:

Create your modules

The next step is to create folders in your repository.

Create an sfdx-project.json file with name core/sfdx-project.json which will create the core folder in your repository.

{
  "packageDirectories": [
    {
      "path": "unpackaged",
      "default": true
    }
  ],
  "namespace": "",
  "sfdcLoginUrl": "https://login.salesforce.com",
  "sourceApiVersion": "61.0"
}

Make sure that the API version is the highest common version between your orgs (i.e. if one org is on version 61 and the other is on version 62 then the API version in the file should be 61).
The end result should look like this:
Create another sfdx-project.json file with the name [your org]/sfdx-project.json (replace [your org] with the friendly name of your org).

Repeat this process to create your other folders, which should also match the friendly names of your orgs. In this example I have the NA folder for my North American Production org, and the EU folder for my EU Production org.

The structure of your repo should look like this:

Note: This is a really important step to get right so double check the setup so far before proceeding. If the repo structure is not correct, you will see this error in Gearset.

Populating your modules

The last step is to populate your modules, this doesn't have to be done all at once so feel free to take a pause and plan how you'd like to build your modules.

Select the copy of the main branch as source and main branch as the target.
If you have a set of metadata you already know is shared between your orgs this should be committed to the "core" module.
If there is metadata specific to only one of your orgs, that should be committed to the org specific module.

Creating your Pipeline

The next step is to create your Pipeline, check out this article for instructions on doing so.

Structuring your source control repository

Promoting a change through a Pipeline using layered modules

Setting up a Pipeline to use layered modules

Modularizing a repository using the setup wizard for layered modules

Populating your layered modules