Gearset has full support for end-to-end continuous integration and continuous delivery without the need for external software such as Jenkins.
Gearset CI can be set up with both Salesforce orgs and version control systems (source control).
Scratch orgs can also be used as a target for CI jobs but are not considered the same as Salesforce orgs - for more information on this, see our support document.
When you create a CI deployment job, Gearset will automatically compare your environments, select the metadata you specify and analyze it to find any dependencies through our advanced problem analyzers. It then builds the deployment package, runs your tests, and deploys the changes. A deployment report is saved in your history, along with the package created, and we'll notify you using your configured options.
You can also create a validation-only CI job (sometimes referred to as continuous validation). This would be recommended if the target is a production org.
Setting up a CI deployment job in Gearset
Before creating a CI job, you first need to have added some connections to your orgs or source control repositories. You can do this via
My connections in the nav menu on the left. Only orgs added with Salesforce authentication method will work. Org connections made with Username and Password will not work.
Navigate to the Continuous integration page, found under
Automationin the nav menu on the left.
ADD NEW JOB....
Give the job a descriptive name (e.g. 'GitHub to Staging').
Select the source connection type (a Salesforce org or a version control system).
If you selected a version control system, select the branch to use and choose whether Gearset should use a package.xml file to control which items are deployed.
Select the target connection type (a Salesforce org or a version control system).
If you selected a version control system, select the branch to use.
Choose how often you want the job to run. If you're using a Salesforce org as the source, this can be every 1, 2, 4 or 24 hours. You cannot set what time of the day the CI job runs. If you're using version control as the source, you can alternatively choose to run the job
when the source branch is updated.
If you choose 24 hours as the runtime, the first automated run will be sometime in the next 4-hour period. The job will then be scheduled to run between midnight and 4 am UTC.
If you choose the latter option, your target is a Salesforce org, and your source is a source control branch, a new box will appear, giving you the option to validate pull requests targeting the source branch.
Specify the test level you would like for the CI job. (See more about test levels for your deployments.)
Select if you would like the job to include
Decide if you want to include changes to user permissions in your CI job; by default, these are excluded. (For more on this checkbox, see our separate support document.)
Notification settingstab, choose if you want to be notified when the job runs, or only if the CI job fails. (See later in this article for further details on notification preferences.)
Metadata filtertab, set the metadata filter you'd like the job to use. This defines which metadata types the CI job will compare and deploy between your two orgs. (See more on custom metadata filters.) For CI jobs, the only standard filter available is the
Default CI comparison (8).
Saveto create the job.
Setting up a webhook for a CI job from source control
When deploying from a source control repository to a Salesforce org, you can configure the CI job to run
when the source branch is updated via a webhook.
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.
When creating a CI job to run when the source branch is updated, after you press
Save, you are then able to select how you create the webhook in your git provider
If you select "Add webhook" under the option "Create a webhook automatically" we will then configure the correct webhook settings for Gearset in your git repository
Alternatively, you can chose to "manually set-up a webhook", where you'll see instructions and a
Payload URL and
As per the instructions in the box above, you need to set up the webhook in your source control system, pasting in the payload URL and the shared secret, and setting the content type to be the JSON format. (GitHub webhook setup pictured below.)
Make sure that the
push setting is selected. (Bitbucket webhook setup pictured below.)
Validate pull requests
For a CI job from a source control branch to a Salesforce org (excluding scratch orgs), which you've selected to run
when the source branch is updated, you also have the option to validate pull requests targeting the source branch (e.g. master). When this box is ticked and you follow the instructions to set up the webhook, this will automatically create a validation-only CI job when a pull request is created.
The process to set up the webhook is very similar to that described above, but this time you need to select pull requests to be a trigger in addition to pushes. Simply follow the instructions that appear on your screen after you have created the CI job in Gearset.
Once this is set up, when you create a pull request (PR) to merge into your specified source branch, we'll receive the webhook from your version control system, and match it up with the CI job. We'll then create a new validation-only child CI job using a copy of the parent job’s settings, except with the PR branch as the source. This will be shown in the Continuous integration dashboard - click on the parent job and the child job will be shown below it.
We'll post the status to your version control system so it shows up on the PR - example screenshot from GitHub below. If all checks have passed, you can merge the PR, triggering the CI deployment job, confident that the deployment to the org will be successful, as the Salesforce validation succeeded. If the validation fails, you know not to merge.
When the PR is merged or closed, we’ll suppress the child job from the Continuous integration dashboard.
If the PR is merged after the child job has successfully validated then the next run of the parent job (the one that is deploying the commit of the PR merge) will attempt to do a Salesforce quick deploy. This means that we promote the validated package from the child validation job to be properly deployed and so we avoid re-running test suites making your CI process faster.
Note this feature is only supported for the git providers:
Azure DevOps Git
And not supported for custom git repo connections.
For more information on the 'validate pull requests' feature, see our blog post.
Setting your notification preferences for CI jobs
Choose whether to get notified after every CI job run, irrespective of the outcome, or only if the CI job fails.
Enter the email address(es) of who to notify of the result.
Gearset also supports SMS notifications (US, UK and Australia only), Slack and Microsoft Teams integration via webhooks, and Chatter integration.
For Slack integration, please see Slack's documentation on how to do this.
To set up the Microsoft Teams integration, please see their documentation.
Validation-only CI jobs
Within Gearset, you can also set up validation-only CI jobs, so you can catch any problematic changes early and make sure that when the time comes to deploy, you’ll be able to release successfully.
To set up a validation-only job, navigate to the Continuous integration page, which can be found under
Automation in the left-hand side menu. To create a new job, scroll down to the Validation only CI jobs section (below Deployment jobs) and select the
Add new validation only CI job button. Now follow the same setup process as with standard CI deployment jobs.
Managing and viewing your CI jobs
The Continuous integration dashboard displays all your current CI jobs, the source and target for each, when the job was last run, and its outcome. When you click on a job, the
Job type will be displayed: either
Validation. For jobs you own, you can manually start a CI job on-demand by clicking on the play button in the actions column. To see the details of every time the CI job ran, click on
For successful CI job runs, you'll be able to download the PDF deployment report, package deployed, and the CSV summary, just like any other deployment in the app.
Note the rollback option is available for deployment CI jobs here. For validation only CI job the deployment and rollback option is available, once deployed, in the Deployment History page.
For CI jobs when the deployment failed, clicking the view errors button will show you the full list of deployment errors. These can be exported as a CSV file for easy reference and debugging.
Temporarily disabling CI jobs
When a CI job is created, it is added in an
Enabled state. This means it will automatically run using the trigger you specified - either every 4 hours, every 24 hours, or when the source branch is updated.
You can stop CI jobs from running automatically by switching their status to
Disabled. A disabled job will not run unless you click the
Run now button (only available if you are the job owner), regardless of any webhooks or timing options set during creation. To switch a job between enabled or disabled, click the slider into the desired state.
(N.B. Only a team owner or the creator of the CI job will be able to change the state of the CI job, or to edit its settings.)
Viewing the static code analysis results of your CI jobs
As well as running during manual deployments and in change monitoring jobs, Gearset’s fully configurable static code analysis now also automatically runs as part of your CI jobs. If you want to find out how to configure your rule set see our help guide.
Gearset will automatically perform your static code analysis (on the classes being deployed) every time a CI job runs. To find your static code analysis results, navigate to the Continuous integration page and click
View history to see the results of one of your CI jobs. Click
View static code analysis issues for any of the job runs to see the code analysis issues for that run.
When you view your code analysis results for each job run, Gearset will display any detected rule violations and group them within the class that they belong to. You can click the menu on the left to view specific violation categories or use the text filter to narrow your results down to a specific class.
For any violation detected, Gearset will tell you which line of code the issue begins on and provide a description of the violation, so you can easily understand why issues have been flagged. For more detailed information on each specific rule, click the name of the rule and you’ll be taken to the PMD library for a more in-depth look at the individual rule and its implementation.
Note that you also have the configuration option to fail the CI job if the static code analysis rules are violated:
Problem analyzers and your CI jobs
As well as running static code analysis, Gearset will apply problem analyzers to all CI jobs. If problem analyzers have applied fixes your CI job, you'll be able to click the
View problem analysis fixes button to view those fixes in detail.
You can read more on how problem analysers affect your CI jobs here.
Filtering CI job history by date
By default, the CI job history will display job runs created in the last 10 days. You can change this filter view by clicking on the date range drop-down menu.