Please note that we now have a wizard to complete this process automatically.

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

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:

You should also make sure that you have set up your user and team-shared source control connections.

Structuring your repository

Start by creating a new repository on your preferred source control provider. In this example I will be using GitHub.

Make sure your repository will have a read.me file, and then create it.

On your main branch 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.
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.

This is a really important step to get right so double check the setup so far before proceeding.

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.

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

How to set up a new source control repository

Promoting a change through a Pipeline using layered modules

Setting up a Pipeline to use layered modules

Modularising a repository using the setup wizard for layered modules