To set up the pipeline, you need to:

  1. create CI jobs to match the environments

  2. create the pipeline to host the environments

  3. add the environments to your pipeline

  4. 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:

  1. from Developer Sandbox to the integration (INT) environment

  2. from the integration environment to the user acceptance testing (UAT) environment

  3. 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:

  • main branch to production org

  • hotfix branch to hotfix org

  • uat branch to the UAT org

  • int branch 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 Custom objects, Layouts, and Lightning pages).

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 main or master branch).

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 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:

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 Save.

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.

Did this answer your question?