⚠️ Before following the steps in this article we highly recommend reading the below blog post to understand the potential consequences of changing the API version in your repository:
By default, Gearset uses the highest API version that your source and target have in common. For example, if your source org is on v66 and your target org is on v63, Gearset uses v63.
The same rule applies when your source or target is a Git repository (including all Pipelines deployments). In that case, the repository's API version is whatever is set in its definition file. For example, if your repo specifies v62, and your target org is on v63, the highest common version is v62, so that's what Gearset uses. To use a newer version, update the definition file in your repo.
The default is a good starting point. As your DevOps process matures, we recommend deciding deliberately which API version to use and when to upgrade it.
How to change it
If you're using… | Change the API version by… |
Updating the version in your repository's definition file ( | |
Overriding it in the comparison's metadata filter |
Pipelines and version control
In an ideal world, you’d change the API version during a deployment freeze. Changing the version mid-release can cause unexpected errors: for example, a change tested in UAT on v62 might fail when deployed to Production on v63. Ideally, test deployments on the new version before rolling it into your Pipeline.
Gearset can't change the repository's API version from within the app, so you'll make this change in your version control system, and you can then promote it through your Pipeline like any other change.
Create a feature branch from your main branch, for example API-update-68.
Update the definition file on that branch:
Salesforce DX format (Gearset's default): in
sfdx-project.json, change the sourceApiVersion value.
Metadata API format: in package.xml, change the version value.
Open a pull request from a developer environment. In your Pipeline, select a developer environment, switch its branch to your new feature branch, and click Create pull request…
Promote the PR through your Pipeline. Each environment starts using the new API version once the PR is merged into it. When it reaches Production, all environments on that path are updated.
Note: Environments that aren't on the path to Production, such as long-term project environments, may need to be synced separately.
Compare and deploy
You can override the API version for an individual comparison, which also applies to any deployment made from it.
Run your comparison from the Compare and deploy page.
On the comparison results page, click the cog icon and select Manage custom filters.
Under Filter options for all types, choose a version from the API version dropdown.
Click Update comparison.
Note: To reuse this filter and/or share it with your team, save it as a custom metadata filter.
CI jobs
Go to the Continuous integration page and find your job.
Click Edit settings.
In the Metadata filter section, choose a version from the API version dropdown.
Click Save Filter. This will give you the option to update the filter for all of the CI jobs in your Pipeline, and you should do so. Then save click
Save CI job
How do I check my org's API version?
In Salesforce, go to Setup > Custom Code > Apex Classes > New > Version Settings. For other methods, see Salesforce's guide: Find Salesforce Edition and API version.
Related: Salesforce Preview and Non-Preview sandboxes explains which API version your sandbox runs on during a Salesforce release.