To set up the pipeline, you need to:
Create CI jobs to match the environments
Create the pipeline to host the environments
Add the environments to your pipeline
Link the environments together in your pipeline.
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:
From Developer Sandbox to the integration (INT) environment
From the integration environment to the user acceptance testing (UAT) environment
From the user acceptance testing (UAT) environment to the production environment.
There is also the hotfix environment that goes into the production environment.
Create continuous integration jobs
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:
mainbranch to production org
hotfixbranch to hotfix org
uatbranch to the UAT org
intbranch to the INT org
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
Creating a new pipeline
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
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.
Adding an environment to your pipeline
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
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.
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:
Adding a Developer Sandbox to your pipeline
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
Linking the environments together
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:
Developer Sandbox → INT
INT → UAT
UAT → Prod
Hotfix → Prod
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.