Skip to main content

How to install the Gearset Connected Apps from a current connection

Installing Gearset Connected apps to keep compliant with Salesforce's latest security policies

Alex Walter avatar
Written by Alex Walter
Updated over 2 weeks ago

Following the announcement by Salesforce that the security policy around Connected Apps is going to change, Gearset is recommending that current users install the Gearset Connected Apps in your Salesforce orgs.

Why are we asking you to do this?

Salesforce made an announcement on 18th August 2025 that they are changing the restrictions on Connected Apps.

Current connections to Gearset should be unaffected by the change, but any future connections either by new users or to new orgs & sandboxes will require the Gearset Connected App(s) to be installed as well as being connected.

There is a straightforward step to install the Gearset app and we are asking users to do this before Salesforce start to roll out the changes to these restrictions.

The Connected App(s) cannot be installed or deployed using the Metadata API, therefore this is a manual process as outlined below.

What to do

For any org that you use to log in to Gearset or use within Gearset, get a Salesforce System Administrator on the org to do the following easy steps, which should take less than a minute:

  1. Go to the Connected Apps OAuth Usage section within Setup in your Salesforce org.

  2. Find the Gearset apps in the list: Gearset, Gearset Deploy (& if you use Code Reviews: Clayton)

  3. Click on Install for each of these apps.
    ​Note: If Uninstall appears rather than Install, this means the app has already been installed and no further action is required.
    ​

  4. Click on Install for each of these apps
    ​

  5. Once installed, check the settings for the app and make sure your policy has a setting for Permitted users of All users may self-authorise.
    ​

Once you have installed the apps, they will now appear in the Manage Connected Apps section like so:

They will also appear in the Connected Apps OAuth Usage section showing they have been installed:

Here is a short video guide on how to do so.

What are the apps Gearset uses?

Gearset uses three connected apps:

  • Gearset - to log in to Gearset

    • this will appear if you or any users log in to Gearset using the Salesforce option (typically this would just be for your production org)

  • Gearset Deploy - to connect an org

    • this will appear for any orgs you connect to Gearset (for metadata deployments, backup, etc)

  • Clayton - for connecting to Code Reviews in Gearset

    • for any orgs you have connected to the Gearset Code Reviews tool

More details in this document.

Troubleshooting

If you are struggling to either log in to Gearset, or connect to your org, please check the settings for the Gearset & Gearset Deploy apps.

  1. Go to Connected Apps OAuth Usage section in Salesforce Setup

  2. Select Manage App Policies for the app

  3. Check to see the policy setting Permitted users .

  • If you have the default setting of All users may self-authorize, Gearset connections will behave in the same way as previously, where users will be able to connect Gearset apps.

  • If you have the setting Admin approved users are pre-authorized, the connection behavior will be different from when the app was not installed. Unless you have explicitly given permission to each of your team, they will no longer be able to access Gearset or connect to the org. Details on how to give this permission is in the Salesforce documentation or follow the guide below.

How to setup permissions for Admin approved users are pre-authorized

If you choose the option of Admin approved users are pre-authorized, you will need to decide a way of allowing users to access the Gearset apps and hence have access to Gearset and connecting and using orgs within Gearset.

Here is a guide using the Gearset Deploy app as an example. Initially the app is setup and has the Permitted users setting of Admin approved users are pre-authorized:

However there are no profiles (1) or permission sets (2) associated with the app, so no one is authorised to use the app:

1. Add profiles to the approved users list

After selecting Manage Profiles, you can choose which profiles you want to access the app. We choose to allow the Sys Admin - EMEA, Sys Admin - Senior & System Administrator profiles but exclude others such as the Sys Admin - Junior & Work.com Only User:

After clicking Save we return to the Gearset Deploy app and see that the users with these profiles can now access the app and use Gearset to connect to the org.

2. Add a Permission Set to assign to approved users

Firstly, create a Permission Set, in this example we have called it GearsetDeploy app permset. Go to the section Assigned Connected Apps:

Edit the Assigned Connected Apps:

Choose Gearset Deploy and add to the right-hand panel for Enabled Connected Apps:

Click Save:

Gearset Deploy will now appear under Assigned Connected Apps:

You can now go and assign this permission set to any users who you want to grant access to via Manage Assignments.

If you now go back via Manage Connected Apps and view Gearset Deploy, you will see that this permission set now appears under the Permission Sets section.

Please note that if you make changes to the OAuth Connected App settings you will need to re-authorise the org connection in Gearset to avoid disruptions when retrieving/deploying metadata and data.

Please reach out via the in-app chat if you have any further questions.

Related Articles
Starting a free trial and creating your Gearset account
Can Gearset connect to orgs with IP access restrictions?
What access does Gearset need when connecting to a Salesforce org?
Why does Gearset have two Connected Apps?
Connecting to a Salesforce org hosted on Alibaba Cloud in China
Did this answer your question?