To set up the pipeline, you need to:

Note: For Gearset’s pipelines to work as expected, make sure to set the branch synced to prod (in this example main) as the Default base branch for new feature branches.

Your pipeline doesn’t have to follow the same order or have the same number of environments, but the following example is a good one if you don’t have another model in mind. This document will walk you through setting up a pipeline with five environments.

This example pipeline starts with the Developer Sandbox, where new features begin their life. Then, following the pipeline from left to right, features will be promoted:

There is also the hotfix environment that goes into the production environment.

If you haven’t set up continuous integration (CI) jobs before, this article will give you the basics. Please also check that the webhook for each CI job is configured.

We want to set up a CI job for each environment in your pipeline. In this example, we will need four jobs that match the four environments:

It’s important to note that all the environment branches need to be cloned from main. Before doing this, it's worth getting rid of irrelevant metadata from the repository. This can include removing metadata that's no longer relevant, and upgrading the metadata to the XML format from the latest SFDC release (this is especially important for Custom objects, Layouts, and Lightning pages).

You can access the pipeline view from https://app.gearset.com/deployment-pipelines and the pipeline button in the Continuous integration dashboard.

In the pipeline view, click on Add new pipeline

You’ll then be asked to input the pipeline name and the git repository you want to connect to the pipeline.

Choose the branch which the feature branches will be created from: For pipelines to work as expected, make sure to set the branch synced to prod (in this example main) as the Default base branch for new feature branches.

Note - Once a repository is set, it is locked to the pipeline and cannot be changed even if the repo was renamed or changed from the Git side.

Run validations on final environment: You can configure validations on final static environments to run automatically For releases only, or for both releases and individual feature pull requests (For all pull requests).

Note: If the Validate pull requests targeting the source branch setting on a static environment is unticked, then no automatic validations will be run for that environment no matter which option is selected for Run validations on final environment.

Auto delete feature branches: This will automatically delete feature branches once they have propagated throughout the entire pipeline.

Note: If you have this setting turned on and you delete a Pull Request, the Branch will also be deleted to keep everything clean.

Pipeline can only be edited by owner: We default the setting to on for any new pipeline being created. When this setting in checked, other Gearset team owners are not allowed to edit the pipeline. Users need to be a Gearset team owners, (instead of a Gearset team member) to be able to edit Pipelines.

Once you click Save, the app will prompt you to set up the webhook, which you need to add for the pipeline to work successfully. Webhooks allow Gearset to detect changes pushed to a repository in real time, without having to poll to see if anything has changed. Whenever you push to the repository you've set up, Gearset will immediately pick those changes up and sync them to your target.

There are two options available, manual and automatic. If you wish to set it up manually, expand the dropdown and follow the instructions.

For automatically adding webhook, click Add webhook:

Note: If there is already a usable webhook set up in your repo, we'll add this job to the pool that webhook serves, and you won't need to add another.

Now you should be able to see a blank release pipeline for you to set up your environments.

If your CI jobs are already set up according to the instructions above, click on the Create Environment button and select Choose from an existing CI job.

Alternatively, click the + Add environment drop-down and select Add static environment. Pick an existing CI job from the list and press Save.

If you’d like to create the CI job at this point, select Create new environment/job instead.

This screenshot shows the addition of the environment that corresponds to “int branch to the INT org” CI job.

Clicking Save will result in this single environment being added to your pipeline:

Repeat this step with all the other environments to add them to the pipeline. Don’t worry that they aren’t linked sequentially or are in the “wrong” order. Your results should look like this:

To add an environment that’s not directly associated with a CI job, you’ll need to add a Developer Sandbox to the pipeline. You can do this by selecting the `+ Add environment` drop-down followed by `Add developer sandbox`.

You’ll be prompted to enter the sandbox environment name and select the sandbox from the list of available org connections. You can now choose if you want to create a new feature branch by selecting Create new branch from main (**the branch for this sandbox should either be a new feature branch created from main, or an existing branch you are not using**). If you prefer, this can be done later. Click Save.

You’ll notice that all the environment boxes now show a circle on their left- and right-hand sides (except for the developer sandbox environment, which will only show it on the right-hand side).

The next step is to link all the environments. First, select Edit environments. This will allow you to drag the boxes around the page to your desired position.

Click and drag the circles to join up the environments in the following order:

You’ll have the option to remove any link, if required. Once the environments are linked, you can select Save changes. The pipeline is now ready to use!

Now that you’ve set up a pipeline, the next document in the series will show you how to promote changes through this pipeline.