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 this article for more details:
How does Gearset handle Salesforce metadata API releases?
What is the latest API version Gearset supports?
Gearset now supports API version 62 (Winter '25). In our app the oldest API version you're able to select is version 37 (Summer '16).
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.
Change API version in Compare and deploy feature
These steps consider that you have already run your comparison from Compare and deploy page by clicking on the blue Compare now
button:
And if you're already on your comparison results page, select the cog icon which is a setting to access Manage custom filters
:
On the next page, you'll see a menu on the right hand side with a heading Filter options for all types
.
On here you can select the dropdown under API version
and amend it according to your needs. Once done, select the blue Update comparison
button in the bottom right.
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 (dropdown under API version
on the right hand side).
Once done, select Save CI job
.
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.
How to check the API version of a Salesforce org?
You can check your Salesforce org's API version by going to Setup > Custom code > Apex Classes > New > Version Settings
.
In there, you can check the API version:
If you're interested, Salesforce's Help Centre documentation shows more ways of identifying your current API version: Find Salesforce Edition and API version.