Continuous integration (CI) jobs in Gearset can be set up to compare a git branch to a target org.

Best practice

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 great best practice 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.

However, we realise that not everyone is able to adhere to best practice. 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

When this 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 branch

and deploy them to the target org.

The metadata filter still applies in this case, so make sure the delta changes you are making to git branch is within the metadata filter types.

This was a feature requested by our users, so if you have any other ideas please let us know!

All git providers are supported for this feature, including custom git connections.

How to enable the feature

To enable this feature, you need to select a git as the source and an org as the target in the CI job settings, and head to the Advanced settings tab and select Enable delta CI for this job. This works for new jobs as well as existing jobs.

This 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 run will be an empty run that establishes a baseline for future commits.

If your CI job setting is set to a set period instead of every update to the source branch, the job will group all the commits since the most recent successful run of the CI job and deploy that.

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.

Known limitations

Sub components

Delta CI works at the component level rather than the subcomponent (defined by the metadata API) level. So if you only change a custom field within the Account object, Gearset will deploy all changes in the entire Account object rather than just the custom field.

For example, if you make a commit which includes a custom field permission on the Admin profile,

you will see the CI job identify other permissions on the Profile as changed.

This is because custom field permission is a subcomponent of the Admin profile, the whole Admin profile will be considered changed and all the permissions will be included in this comparison.

Due to the fact that the metadata filter is not retrieving the custom object from the org side, while retrievable on the git side (see Profiles, permissions and other junction objects section of this document), this results in the custom field permissions showing up as New.

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 , the customObject will be considered together.

  • When deploying customObjectTranslation , the customObject will be considered together.

  • When deploying translation , the corresponding metadata type may 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 the problem with validation only CI jobs: as 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 substitute. we'd love to hear from you.

Did this answer your question?