Skip to main content

How do I change the API version that Gearset uses?

How to change the API version Gearset uses for a deployment

Richard Terry avatar
Written by Richard Terry
Updated this week

By default Gearset will look at your source and target and choose the highest API version that's supported by both.

When getting started with your Devops journey this works well as it gets you going quickly. As you look to mature your process, it's recommended to build a process to understand what API version you should be using, and when to update it.

For more information about building the correct process your team we recommend reading the below blog post:

Index

Changing the API version in your repository (Version Control System)

To update the API version in your repository, you need to update the definition file. If your repository is in SFDX format (Gearset's default format), this information will be stored in the sfdx-project.json file. If your repository is in MDAPI format, the information will be in the package.xml.

If these files aren't present, Gearset will try to determine 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.

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.

How to update the API version used in your Gearset Pipeline

We recommend updating your API version during a deployment freeze.

This is because by changing the API version used in your pipeline you will change how deployments work into your orgs.

For example, if you have tested a deployment in UAT using v62, and then deploy to Production using v63, you could hit unforeseen errors.

As mentioned at the start of this document, we recommend you have a process established for updating your API version. It's best to test deployments with the new API version before moving the change into your Pipeline.

For further reading on that topic:
Regain control of Metadata API versions and Salesforce platform upgrades

Once you are ready, you can follow the steps below to update the API version used in your Pipeline.

You need to do this directly in your Version Control System(VCS), as Gearset can not update the API version in the app.

1. Create a new feature branch from your main/master branch in your VCS. In this example, it's called: API-update-63.

2. Find your definition file in the repo and update it with the current API version.

To do this, you can follow this guidance referenced at the beginning of this article.

In the example below, the VCS provider is GitHub, and the API version is being updated to v63 in the sfdx-project.json file, as the repo is using the Salesforce DX source format.

3. In your Gearset Pipeline, select one of your Dev org environments, and change the selected branch to the new feature branch you have created.

Then click Create pull request....

4. Deploy this PR down the Pipeline like any other PR. After this is merged to the next Pipeline environment, that environment will now be using the new API version.

5. Once the PR with API change reaches Production, all environments will be updated and will be using the latest API version.

Note: You may need to sync this to any environments in your pipeline that were not covered on the way to Production, such as a any long-term project environments.

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 the API version in a Compare and deploy comparison

These steps should be followed if you have already run your comparison from Compare and deploy page by clicking on the blue Compare now button:

Once on the 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.

Change the API version in a CI job

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.

What is the latest API version Gearset supports?

Gearset now supports API version 63 (Spring '25). The oldest API version currently supported is version 37 (Summer '16).

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 Center documentation shows more ways of identifying your current API version: Find Salesforce Edition and API version.

Did this answer your question?