All Collections
Comparisons and deployments
How do I change the API version that Gearset uses?
How do I change the API version that Gearset uses?

Gearset will try to choose the best API version depending on your source and target, but sometimes it can be useful to override that choice

Valerio Chang avatar
Written by Valerio Chang
Updated over a week ago

In most cases, you don't need to worry about which API version to choose when deploying using Gearset - we'll automatically pick the highest API version that's supported by both the source and target of your comparison.

In the case of source control or file-based comparisons, Gearset will try to detect what API version your metadata is in, by looking in the package.xml file (MDAPI repos) or sfdx-project.json file (SFDX source format repos). If these files aren't present, Gearset will try to deduce the version based on the types of metadata in the repository. If Gearset still can't tell, it will default to assuming your metadata is in API version of the current supported default (see here for more details). 

Changing the API version in the repository

Should you wish to update the API version in your repository, you could do so by editing the definition file.

Salesforce DX source format repo

Locate your sfdx-project.json file and change the sourceApiVersion value, as shown in the screenshot below.

Metadata API format repo

Locate your package.xml file and change the version value, as shown in the screenshot below.

Changing the API version in the 'Compare and deploy' and CI jobs

Occasionally it's useful to be able to override the API version that Gearset has picked. This is done through the metadata filter dialog.

For the 'Compare and deploy' comparisons

On the Compare and deploy page, open the metadata filter menu at the bottom of the screen, and then select Manage custom filters...

Use the drop-down at the bottom of the Manage custom filters dialog to select an API version for your comparison:

This API version will now be used for retrieval from Salesforce, and any deployments that result from the comparison.

Optionally, you can save this selection into a custom filter for re-use later and to share the setting with the rest of your team. For more information on this, see the Custom metadata filters article.

For CI job comparisons

On the Continuous integration page, open the CI job dashboard to view your CI jobs.

Search for the CI job that you want to use a different API version, then click Edit Settings to adjust the metadata filter.

Then go to the Metadata filter section of the CI job settings, where you can adjust the API version Gearset uses.

Note: If you are using a Git branch as a source, you need to update the sfdx.json file mentioned above. This is because only setting the API version in the Gearset metadata filter will not override it.

Did this answer your question?