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

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

In order to support the creation of new modules in your repository, you must convert the structure of your repository. You can do this through Gearset's automated modular repository setup.

Step 1 - What does it mean to modularise a repository?

This process will allow you to create modules within a single repository. You will be able to define sets of code as "core" (shared metadata between all of the orgs you deploy to) or "org-specific" (code belonging to specific orgs).

Step 2 - What do you mean by create a module?

A Gearset module is a folder in your repository that contains your org's metadata. The core module contains the shared metadata. Gearset will create these folders for you.

Step 3 - Why create an org-specific module?

Creating an org-specific module will generate a new module, and pair it with the existing "core" module. On deployment, any org-specific metadata within that module will be combined with the shared metadata from "core".

Step 4 - Why are the modules layered?

Creating a core module that contains metadata shared by all of your connected orgs allows you to build a change once, and have it simultaneously deployed to all orgs. Creating an org-specific module allows you to build changes specific to that org without danger of rewrites.

Step 5 - How can you section your code into modules?

If metadata is shared between all orgs, it can be placed in the core module. Metadata specific to individual orgs should be placed in the relevant org-specific module.

Step 6 - Convert repository

At this step, you will see a warning message telling you that you are about to change your repo structure. If you wish to continue, click the checkbox for I understand this will change the structure of my repository and click Convert repository.

Note: Once you convert your repository, it is permanent.

Step 7 - Commit to core

If you have a set of metadata you already know is shared between your orgs this should be committed to the "core" module.

Step 8 - Create a new module

Once you commit the metadata to the core module, it is time to create your org specific modules. You can do it by clicking on + Create new Module.

You will be presented with a new window to create a new layered module. Enter the module name and click Create.

Step 9 - Update modules with sfdx-project.json files

Gearset will have automatically created a .placeholder file in the module folders, you will need to replace these with an sfdx-project.json file.

Note: This step needs to be completed for all new modules including the core module.

Step 10 - Commit to new module

You will now have the option to commit to the newly created module as shown below. If there is metadata specific to only one of your orgs, that should be committed to the org specific module by selecting that module.

This doesn't have to be done all at once so take a pause and plan how you'd like to build your modules.

Once you have created your modules you will be able to set up a Pipeline to deploy to multiple production orgs.

Check out these articles next: