To run comparisons and deployments involving Salesforce orgs in Gearset, you'll need to set up some org connections.

Gearset allows you to connect to any type of Salesforce org:

  • Developer orgs
  • Sandbox orgs
  • Production orgs
  • Salesforce DX scratch orgs (see our article on DX orgs for more info)

Gearset also supports SSO and My Domain connections to your orgs.

By default, Gearset connects to orgs using the secure OAuth method (our recommended approach). If required, you can also connect to orgs using username/password connections.

The Salesforce user you connect to your orgs must have the Modify all data permission in order to run comparisons and deployments through Gearset.

Adding a Salesforce org connection via OAuth

OAuth is the recommended method for connecting to all orgs.

  1. You can add an org from either the Compare and deploy page or the Salesforce orgs page in the Gearset app.
  1. Select either Salesforce authentication or My Domain / Government Cloud  as the authentication method, depending on the org you're connecting to.
  2. Enter the Salesforce username for the org you wish to connect to.
  3. If you've selected My Domain / Government Cloud, enter the custom domain you use to connect to your org.
  4. Select the Salesforce org type from the drop-down: Developer, Sandbox or Production. (Note that the Salesforce login for developer orgs is different than that for sandbox orgs.)
  5. Click Authorize. You'll be prompted to log into your org through Salesforce.
  6. Click Allow when prompted, to grant Gearset access to the org via OAuth.

The org will now be added to your list of saved connections. You can now select it for future comparisons or automated jobs from the org selector drop-down.

Adding a Salesforce org connection via username/password

  1. You can add an org from either the Compare and deploy page or the Salesforce orgs page in the Gearset app.
  2. Select Username/password as the authentication method.
  3. Enter the Salesforce username for the org you wish to connect to.
  4. Enter your org password.
  5. Enter the org security token (if required).
  6. Select the Salesforce org type from the drop-down: Developer, Sandbox or Production. (Note that the Salesforce login for developer orgs is different than that for sandbox orgs.)

The org will now be added to your list of saved connections. You can now select it for future comparisons or automated jobs from the org selector drop-down.

Adding a friendly name to a saved org

You can add names to your connected Salesforce orgs to make them easier to identify.

  1. From the Salesforce orgs page, click + Add under the Friendly name column.
  2. Enter the name for the connection.
  3. Click Save.

Managing saved org connections

All of the org connections you have added to Gearset can be seen on the Salesforce orgs page in the app.

This page lists details for orgs you have added yourself, and (in a separate section below that) any orgs that have been shared with you by members of your team.

On the left-hand side you can choose to view All orgs or particular types of orgs, such as Developer orgs.

The table displays the following information:

  • Owner: who owns the org connection. If a team member has shared access to one of their orgs using Gearset's team features, you will see their initials (hover over to see the full name) in this column.
  • Entitlement level: your access level to the org - this is particularly relevant for shared org connections. See our sharing org credentials guide for more information about delegated access.
  • Username: the Salesforce username for the org connection.
  • Organization type: Developer, Sandbox, or Production org.
  • Friendly name: the custom name you've given that org connection (if any).
  • Dev Hub: whether the org has had Dev Hub enabled (within the Salesforce UI).
  • Scratch orgs: the number of scratch orgs created for each Dev Hub. (See our separate support document for further details.)

You can manage your saved org connections from this page, using the Actions column. You may need to click on the arrow icon (for non-Dev Hub orgs) or cog icon (for Dev Hub orgs) to display additional actions.

  • Delegate access: share this org credential with members of your team in Gearset, to allow them to compare, validate to, or deploy to it.
  • Re-authorize: if the OAuth token has expired for a saved connection, use this to re-enter your user credentials and refresh the connection.
  • Delete org: if you wish to remove a saved org connection, click the bin icon. (It will delete the connection, not actually delete the org!) If this org was shared with any team members, this will also remove it from their shared connections.
  • Create scratch org: for orgs that are Dev Hubs, you can create scratch orgs here. (See this support document for more information.)
  • Remove shared org: for org connections shared with you by a team member, you can click the broken link icon to remove the org connection. This doesn't delete the connection from their account. To regain access to this connection, ask the org connection owner to re-share it.
Did this answer your question?