Continuous integration (CI) jobs in Gearset can be set up to compare a git branch to a target org.
Standard CI jobs
Standard CI jobs in Gearset will compare all the metadata (restricted by the metadata filter you've selected for that CI job) that is in the environments, and (depending on the difference types you've specified in the settings) deploy typically all the new and changed items (and optionally deletions) to the target org.
This is one of the ways to keep the source and target in sync and achieve a source driven development flow, where the source of truth (your git branch) is deployed to your org environments automatically.
You can read more about our CI jobs in these articles:
- Continuous integration
- Setting up your first CI job in Gearset
How is Delta CI different to standard CI?
However, imagine you just made a commit to your git branch, and the commit only contains the Account custom object, and you want to automatically deploy this to the target org...
but you don’t want to deploy all the differences between the two environments
but you don’t want the hassle of reconfiguring your metadata filter on the CI job to pinpoint the change you made
but you don’t want to wait ages to compare the whole set of metadata (sometimes your CI job may run too slowly to be able to take advantage of validating PRs)
Now you can get around this with the delta CI feature.
Delta CI's intended functionality
When the Delta CI feature is enabled, the CI job will take all the differences of the components between:
your latest commit in your Git source and
the commit that was in the most recent successful CI deployment from this Git source branch
And then it will deploy all these differences to the target org (of the CI job).
The source commit (highlighted above) tells the CI job which components have changed on the branch and need deploying.
Note that if there are failed validations in commit on the branch to the org, there will be multiple commits between the latest commit in your Git source and the commit that was in the most recent successful CI deployment, resulting in multiple commits to take into account when executing the Delta CI run.
The Delta CI job will take all of the components that have changed, pull those components from the latest commits in your branch, and deploy the whole file for these components to the target org.
Delta CI on validation PR job runs
When the Delta CI feature is enabled, the validation PR CI job will take all the differences of the components between:
your latest commit in your feature branch (this will also be the source branch of the PR)
plus any commits that failed deployment on your CI source branch (this will be the base/target branch of the PR), and
the commit that was in the most recent successful CI deployment from this CI source branch
And then it will deploy all these differences to the target org (of the CI job).
What effect does the the metadata filter have on the Delta CI job?
The metadata filter and the package.xml filtering still applies in this case, so make sure the delta changes you are making to git branch are within the metadata filter specified in your CI job settings.
To find out more about how Gearset determines which metadata items are selected, please refer to this guide:
Why did Gearset introduce Delta CI functionality?
This was a feature requested by our users, so if you have any other ideas on how we can improve Delta CI, please let us know!
All git providers are supported for this feature, including custom git connections.
Note: You can now deploy Vlocity or OmniStudio components with Delta CI.
How to enable Delta functionality in the CI job settings
To enable this feature, you need to select a git as the source and an org as the target in the CI job settings. Then in the next stage you can choose to use Delta CI.
If you wish to edit an existing CI job then on your CI dashboard select Edit settings... on the CI job you want to amend, then click on Advanced tab, and select checkbox Enable delta CI for this job.
Note: Delta CI feature is only available for deployment CI jobs and not validation only CI jobs. This setting cannot be disabled once enabled.
Once this feature is enabled, the first Delta CI run will be an empty run that establishes a baseline for future commits.
Deployments made after this on an existing CI job will only deploy commits made after this 0 deployment baseline run.
If your CI job settings are configured to run the job at a specific (period of) time instead of every time when the source branch is updated, the job will group all the commits since the most recent successful run of the CI job and deploy them altogether.
After creating the Delta CI for the first time, in Salesforce, it will display an empty deployment, as shown below. Since this was a baseline run, no changes will be deployed.
What to do if a build fails
Delta CI works by looking at the changes in your commit/branch and deploying those. If the deployment fails, then you should either revert the pull request (instructions here) that caused the failure, or fix the error. The next run will include everything changed including the fix.
What about validating PR jobs
When Delta CI is enabled on a deployment CI jobs, the most recent successful run is in the main deployment job, not the validation job. So it will validate everything that's changed between the current head commit of your feature branch, and the commit of the most recent successful run in the parent deployment job.
On top of that, the different runs within the validation job are independent.
Known limitations of CI jobs
Dependencies
Gearset will determine the dependencies between some metadata component, and pull in other components as part of delta CI to keep the deployment successful.
Some examples are:
When deploying
workflowRule, thecustomObjectwill be considered together.When deploying
customObjectTranslation, thecustomObjectwill be considered together.When deploying
translation, the corresponding metadata type will be considered together.customApplications
customLabels
customPageWebLinks
customTabs
globalPicklists
quickActions
reportTypes
scontrols
flowDefinitions
prompts
Why there are no delta validation CI jobs
After testing out the delta CI deployment jobs, many users have asked us to extend the delta CI feature to the validation only CI jobs.
However, we have not been able to implement the feature meaningfully, and we’d like to explain why.
Delta CI jobs deploy everything in the source git branch that has changed since the most recent successful deployment from that branch.
The difference displayed in the run is between:
the new metadata items in the last commit on the source branch, and
the previous commit on the source branch, when the most recent successful deployment occurred to the target organization
This is a specific problem with validation only CI jobs - because the validation CI job does not deploy metadata to the target, there is no previous commit which can be used as a substitute to the most recent successful deployment.
As a result, we can't generate a delta CI job run in the same way as we can for deployment jobs.
We have considered several options, but we have not identified yet a suitable alternative to compare against. If you can think of any possible substitutes, we'd love to hear from you.
Problem analyzers
By default, the CI job will accept all problem analyzer suggestions, you can change which problem analyzers run by using a problem analyzer template.
Any problem analyzers that remove items from the deployment package are not triggered.
How changes of metadata filter affect your CI job
If you made a change to a metadata type, but the metadata type was not included in the CI job metadata filter, the delta CI job run will not compare, and therefore it will not deploy it.
After you edit the filter to include the metadata type, subsequent run will not pick up the commit made before the metadata filter change. It will only pick up commits after the metadata filter change.
As a solution, you would have to run a manual deployment to move this commit (made before the metadata filter change) into the target org.