Gearset allows you to create a new CI job directly from Pipelines page in our app.
This will create a CI job and automatically assign this to your Pipeline. After you've done this, simply link your CI job to other static environments (CI jobs) in the Pipeline.
Step by step instructions
First, on the Pipeline screen, select + Add button.
Select Add static environment, which essentially means you're adding a CI job.
Next, select Create new if you're adding a CI job from scratch.
Or select Choose existing if a CI job has already been created and if it shows on the list of your CI jobs (e.g. if you're migrating an existing CI job into a new Pipeline).
For the purpose of this guide we've selected Created new, which leads users to below configuration page.
CI job can only be added to the Pipeline if:
The source is Git with the repository matching the repository used for a given Pipeline. The target of the CI job must be a Salesforce org.
In the settings of the CI job:
Run joboption is set towhen the source branch is updated. And a webhook has been added as a trigger for the job.The same CI job hasn't already been added as an environment to any other Pipeline!
Environment type
To create a new deployment job, select Deployment environment.
Deployment environment - it's a recommended option as this type of CI job will allow Pipeline users to deploy to the Salesforce org configured as the target of the CI job.
Validation-only environment - this option should be used only in scenarios when the intention is that the CI job doesn't perform any deployments to the target org (e.g. when you want to test the Pipeline and not deploy any metadata).
Basic configuration
On this page you will define:
Environment name - This is a friendly (custom) name for your CI job environment. This name will be shown both in your Pipelines UI, and on the CI jobs page (under "Job name").
Source branch - select the source branch for your CI job. Usually, this would be a long-lived branch defined for your CI job environment (e.g. INT, UAT, QA or Main/Master).
Target salesforce org - select the org to which your CI job will perform deployments (e.g. INT, UAT, QA or Prod org).
Deployments - deployment behaviour
On this page you'd need to decide which deployment options should apply to this CI job environment.
Usually, Gearset users opt for validating PRs against their CI job environment as it helps to verify that the deployment to the org will succeed.
Validate pull requests - enabling this option ensures that Gearset runs validations for any PRs (Pull Requests) targeting the source branch and the Salesforce org used in this CI job (see documentation).
Deploy deleted items - by enabling this option you configure your CI job to also deploy any deleted items that are added to your PRs (or to the source branch of the CI job).
See documentation on what destructive changes Metadata API does not handle).
Deploy permissions - by enabling this option you instruct the CI job to also deploy user, system and app permissions (see documentation).
Deployments - tests
On this page you can define:
Apex unit tests
Run tests - customise your CI job to run either "Salesforce default tests", all your tests or specific (custom) tests, or no tests at all (see documentation).
Run LWC tests - enables Lightning Web Component tests
(see documentation to ensure your repo is setup correctly prior to running these tests).
Agentforce tests - if your deployment(s) contain Agentforce metadata, enabling this option will trigger Testing Center tests after a successful deployment to the target org of the CI job.
Automated UI tests - decide if you want to run UI tests which are triggered after a successful org deployment. The results of the tests are shown on the CI jobs page (see documentation). You can also opt for CI job to not run any tests at all.
Deployments - code quality
On this page you can further customise deployment configuration of:
Static code analysis ruleset - This option allows you to use Gearset standard ruleset for SCA.
In addition, you can configure CI job run to not fail the deployment when it runs into the static code analysis (SCA) issues, or to fail the job run if it encounters errors and warnings, or only errors.
Check our documentation on what static code analysis is, and how to configure your own set of rulesets.
Code coverage level - minimum requirements from Salesforce is that code coverage has an average threshold of 75%.
Using the "Fail validation based on minimum code coverage level" option, you'll be able to enter a custom % value for minimum code coverage level (note that this value must be 75% or higher, otherwise you won't be able to save your CI job).
Metadata filters
In this section you can configure your metadata filter for the CI job. Gearset has documentation on managing custom filters in CI jobs.
If you're adding a new CI job to already operational Pipeline, ideally you'd want to use the same filter that is in use in all the other jobs in your Pipeline. This ensures consistency during metadata deployments through the Pipeline.
Advanced
On this page you can connect a webhook to your CI job for any third party integrations. Learn more about using outgoing webhooks in CI jobs.
Description - your custom description of what the webhook does.
Outgoing webhook URL - is where you enter the URL you'd like Gearset to
POSTto.Triggers - defines the events that trigger the webhook, these can be either
successfulorfailureevents, or both if that's your preference.Payload - allows you to choose Gearset's default option which is:
Gearset's standard payload that includes some basic information about CI job run (see documentation)
Or alternatively configure your custom payload (read more about custom payload's options and variables)
You can also select Glip, which is an online messaging platform from RingCentral, similar to Slack (see documentation on Glip integration).
Notifications
On the last configuration step, you can instruct your CI job to send notifications either on every run or only if the CI job fails.
Gearset also allows you to send these notifications via a text message (SMS) to contry codes: +44 (UK), +1 (USA, Canada) or +61 (Australia). You can select multiple mobile numbers.
Add notification method - in addition, this option allows you to add different notification methods, such as Email, Slack integration (URL), Microsoft Teams (URL), or Chatter Subject (ID).
Final steps
Once you're done with all the above settings, click on Save environment.
Gearset will automatically confirm if the webhook set up has been successful.
After you click Finish, Gearset will take you to the Pipelines UI page directly to the Pipeline for which you've added this CI job.
From there, you'll need to link your CI job (new environment) with other environments that are already linked in the Pipeline.
Demo of how to link a new CI job within an existing Pipeline
A quick video demonstration where we've added a new CI job (INT) to an existing Pipeline, and we're placing that environment in the middle, so as a link between the two Dev orgs and the Prod org.
That's it!
Your Pipeline is ready and you can now start promoting changes to and through the newly added environment (CI job). Good luck!