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.
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.
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 from where the feature branches will be created (we recommend using the
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. Click
Add webhook :
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 create a feature branch by selecting
Create new branch from main. 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.