Continuous integration
Automatically deploy changes from one metadata location to another with CI and CD from Gearset
Jacob Joshua avatar
Written by Jacob Joshua
Updated over a week ago

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 Automation in the nav menu on the left.

  • Click on Add new deployment 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.

  • Now you can choose if it's for a Deployment only CI job or a Validation only CI job.

  • Validation-only CI jobs - This is mainly for catching any problematic changes early and make sure that when the time comes to deploy, you’ll be able to release successfully.

  • 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 your target is a Salesforce org, and your source is a source control branch, there will be an option to validate pull requests targeting the source branch and will have an option to send a notification each time a pull request is validated. The notification is sent based on your set-up for your notification settings (via email, slack, chatter, etc.).

  • Select if you would like the job to include New items, Changed items, and Deleted items.

  • 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.)

  • On the Metadata filter tab, 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).

  • Static code analysis (SCA) reviews your source code to detect common bad practices, catch bugs, and make sure development adheres to coding guidelines. You can select that on this page.

  • You can set an outgoing webhook as part of continuous integration jobs in Gearset. This is documented here.

  • Here you can select the Problem Analyser templates.

  • On the Notifications, choose if you want to be notified when the job runs, or only if the CI job fails.

  • 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 or Microsoft Teams integration via webhooks, into a specific channel,

    • and/or Chatter integration, straight into your org.

  • Click Save to 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 Shared secret.

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 that this feature is only supported for the following git providers:

  • GitHub

  • GitHub Enterprise

  • Bitbucket

  • Bitbucket Server

  • Azure DevOps

  • Azure DevOps Server

  • GitLab

  • GitLab (Self-managed)

  • AWS CodeCommit

Validating pull requests is not supported for custom git repo connections.

For more information on the 'validate pull requests' feature, see our blog post.

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 Deployment or 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 View history.

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

(Please Note: 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 analyzers 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.

Did this answer your question?