This article will run through the steps to set up a pipeline in Gearset.
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.
As a pre-requisite, ensure that you have your source control repository seeded correctly.
How to set up your first Gearset pipeline
To set up a Gearset pipeline, first go to the side menu on the top left corner in our app, and select Continuous integration:
From there you will be taken into the Continuous Integration dashboard, where you will need to select the pipelines icon in the top right corner:
From this screen you click on the blue button Create Pipeline:
Then below pop-up window will appear. Here you will need to fill in the following information:
List of settings to configure in your new pipeline
When creating your pipeline, the settings you'll need to configure are:
The '
Name' of the pipeline.The '
Repository type' (GitHub, GitLab, Bitbucket, Azure DevOps etc) as well as the repository that the pipeline will be based on.
On below example we've selected GitHub because it's the only repository type connected on the Gearset account (that's why it shows up underConnected Git Providers)Note: Once a repository is selected, it is locked into your pipeline. Renaming that repository later in Git will not be recognized and you will need to recreate the pipeline from scratch.
'
Default base branch for new feature branches'
We recommend using Main as the default branch, so that features are always created from a copy of your Production org. This is because Gearset uses the pipelines branching model.'
Feature branch format' (optional setting)
Allows you to select a pre-defined template for the format of your features branches in the Pipeline. Available pre-defined formats are[id]or[id]/[story_name].
Read more about this feature in our documentation:
Feature branch format - optional Pipeline setting
Note: This option may be greyed out if you're creating your first Pipeline, in which case you'd see below notification:
"You must enable Jira or Azure work items to select a branch name template."
In this scenario you can skip this option during Pipeline creation, as this can be configured later. This setting is optional, therefore isn't required for the correct Pipeline functionality.
'
Create back propagation pull requests'
Here you can choose the behaviour of back propagation.You have two options to choose from:
Only when changes are promoted into the final environment
When changes are promoted into any adjacent environment
'
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 (which essentially means: for all pull requests).
Note: If the Validate pull requests targeting the source branch setting (screenshot below) on a static environment is unticked, then no automatic validations will be ran for that environment no matter which option is selected for your pipeline setting: Run validations on final environment.
'
Auto delete feature branches'
Choose whether or not to automatically delete feature branches.
Note: This option will automatically delete all feature branches that no longer have any pull requests coming from them.
'
Pull requests descriptions'As a pipeline owner you can choose whether to Require pull request descriptions for all the PRs (pull requests) created in the pipeline by other team members.
'
Copy VCS Reviewers'Choose whether or not to Copy VCS Reviewers to the new promotion PRs when promoting through environments.
'
Only Editable by pipeline owner'Choose whether or not the pipeline can only be edited by the owner, or any user in the team (if you leave the option turned off).
Note: Functionality of this setting depends on whether it's a team-shared pipeline or not. This setting only applies to user-owned pipelines that have an individual owner.
Team-shared pipelines are by default owned by the team, and not by an individual owner. Find out more about team-shared pipelines.
10. 'Developer sandbox visibility'
With option Team members cannot view other users' assigned sandboxes you can simplify the pipeline view for your team members. Achieve it by filtering out the dev sandboxes that have been assigned to others on the team, and are therefore not relevant to them.
Example: Useful feature if you want to disable the preview of Dev Sandbox A from a developer who should only see their own Dev Sandbox B in the Pipeline preview (because Dev Sandbox A belongs to another developer/team member).
Otherwise, by selecting Team members can view all sandboxes every team member on the team will be able to view all Sandboxes present within your Pipeline setup.
Find out more information about this feature in Assign sandboxes to your team.
Next steps: after you've configured your Pipeline settings
Once you have configure all the above settings and selected Save, which would created the pipeline, in the next step Gearset will ask you to set up a webhook.
It is recommended to click the Add webhook button and Gearset will automatically create the webhook for you:
After selecting Add webhook, Gearset would notify you once the webhook is set up correctly:
A quick video to demonstrate the process:
You can also manually set up a webhook by following the instructions in the dropdown menu.
In this example we can see the instruction for webhook set up in GitHub):
Creating your first environments (CI jobs) in the Pipeline
Within Gearset pipelines, a (static) environment is the continuous integration (CI) job.
CI job is running from the long lived branch (also referred to as an 'environment branch') to the org, syncing those features from the branch into your org.
Once the webhook setup has been completed, then on the dropdown menu in the top left corner you can see your, currently empty, user-owned pipeline.
Note that blue arrow on image below shows a team-shared Pipeline after it had been converted from a user-owned Pipeline, that's why it's available under TEAM-SHARED dropdown.
You can proceed to create your fist environment. To do so, select Create environment...
You will then be able to create a new environment from scratch. To do so, select Create new environment/job:
Hitting this button will take you to our Continuous Integration (CI) job wizard, where you will be able to easily create CI jobs.
Find out more about how to set up your first CI job in Gearset - this article will lead you through the set up and job configuration settings.
Adding static environments to the Pipeline
Once the first CI job has been created, new CI jobs can be added by clicking on Add button in the top right corner of the screen (which stands for adding a new environment), and then selecting Add static environment:
In this example CI jobs for INT, UAT and Main will be created (these are your static environments with long-lived Git branches):
Currently, there are no links between these environments. We will add those links later.
Adding Developer Sandboxes
Next, we will add developer sandboxes into the pipeline (if needed).
You can add these by clicking the Add button and selecting Add developer sandbox:
You will be given a new wizard with 6 different configuration options, which we're describing below.
Sandbox environment name: simply name this sandbox environment.
Git provider: This option will be pre-selected for you. It allows you to only check that the Git provider is correct.
Source repository: Same as with Git provider. It's a pre-selected option based on the source repository used in your Pipeline. If it's correct, you can move on.
Developer sandbox: Select a Salesforce org that will be the target of your CI job.
Assign to team member: You can optionally assign a dev Sandbox to a team member (Note: team member must be on your Gearset team).
Sandbox assignment to a specific team member can be changed later on if needed.
More information on this feature in our documentation: Assign sandboxes to your team.Choose an environment to connect the sandbox to: This option allows you to connect the Dev environment you're adding to one of the pre-existing static environments (CI jobs).
In this example 3 developer sandboxes (Dev1, Dev2 and Hotfix) have been added. We now have 3 static environments (CI jobs) + 3 Dev environments:
Linking Environments together to form the pipeline
To turn these environments into a pipeline, on your Deployment pipelines page use the Edit environments button and link the environments using Gearset’s simple drag and drop system:
Once you've connected all the environment and designed your pipeline, select Save changes:
On clicking Save changes, Gearset will automatically arrange the pipeline display in the order of flow from left to right and you can begin to use it to push new exciting features to your users.
Setting up Jira/Azure work items
To be able to use the pipeline to its full potential, we recommend adding in a ticketing system. Within the pipeline we support Jira and Azure work items. We have documents outlining how to set up these connections to automatically update ticket status when reaching certain environments.
For more information, check the following articles:
Now that you’ve set up a pipeline, the next document in the series will show you how to promote changes through this pipeline: