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)
Want to know what orgs you can connect on your trial? See here for more details.
Gearset supports 3 ways to connect to your orgs
Salesforce authentication or OAuth
My domain or Government cloud (also known as custom domain)
Username and password
By default, Gearset connects to orgs using the secure OAuth method (or Salesforce authentication, which is our recommended approach).
The Salesforce user you connect to your orgs must have the Modify all data permission in order to run comparisons and deployments through Gearset.
Team Owned Orgs
When you add organizations in Gearset, you have an option to add them as a team-owned shared Salesforce org or as an individual.
When you add them as team-owned Salesforce orgs, shared connections are available for use in compare and deploy, validation jobs, unit testing jobs, data backup jobs and CI jobs. Support for data deployment is not yet available.
Adding a Salesforce org connection via OAuth
OAuth is the recommended method for connecting to all orgs, as not all features and functionality work with other methods of connecting.
You can add an org from either the Compare and deploy page or the Salesforce orgs page in the Gearset app.
Select either
Salesforce authenticationorMy Domain / Government Cloudas the authentication method, depending on the org you're connecting to.Enter the Salesforce username for the org you wish to connect to.
If you've selected
My Domain / Government Cloud, enter the custom domain you use to connect to your org. See this documentation for further information.Select the Salesforce org type from the drop-down:
Developer,SandboxorProduction. (Note that the Salesforce login for developer orgs is different from that for sandbox orgs.)Click
Authorize. You'll be prompted to log into your org through Salesforce.Click
Allowwhen 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
You can add an org from either the Compare and deploy page or the Salesforce orgs page in the Gearset app.
Select
Username/passwordas the authentication method.Enter the Salesforce username for the org you wish to connect to.
Enter your org password.
Enter the org security token (if required).
Select the Salesforce org type from the drop-down:
Developer,SandboxorProduction. (Note that the Salesforce login for developer orgs is different from 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.
Limitations
Note that the following jobs are only available for connections made using Salesforce authentication and not orgs added via username/password.
monitoring
unit testing
continuous integration
data deployment
data backup
For metadata comparisons, orgs connected via username and password will not populate the named item list in the custom metadata filter.
Adding a friendly name to a saved org
You can add names to your connected Salesforce orgs to make them easier to identify.
From the Salesforce orgs page, click
+ Addunder theFriendly namecolumn.Enter the name for the connection.
Click
Save.
Managing saved org connections
All 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.Remove connection...: 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 connection: 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.Run CPQ External ID setup: More information on this here.
Common issues
Here are some common issues and how to resolve them when adding new org connections.
Check you are using the right organization type
The authentication process is handled by Salesforce, not Gearset itself. So it's worth confirming you are selecting the right Salesforce org type.
Production organizations and Developer organizations will authenticate against https://login.salesforce.com/
Sandbox organizations should try to authenticate against https://test.salesforce.com/
As the different organizations types use two different authentication flows but have a similar UI, it's easy to accidentally click on the wrong account type when logging into Gearset. It's always worth double-checking you're using the correct flow.
Reauthorization or re-adding needed after sandbox refreshes
When your sandbox orgs get refreshed, there may be a need to reauthorize the org connections in Gearset.
The error message that you may get is in the format of A Gearset account with the Salesforce username [email protected] hasn't been created yet
This is due to the fact that when Salesforce sandbox orgs get refreshed, your Salesforce OAuth token can be invalidated. This will invalidate the Gearset org connection and require a re-authorization of the connection.
There is also the possibility that you cannot reauthorize and need to remove the connection and re-add the sandbox.
Does your organization type enforce a custom domain?
If you have an org with a restrictive domain setting like this
You can add your org with the steps listed here.
Error "incorrect username or password" after sandbox refresh
When you have refreshed your sandbox and try to re-add the org, some users have reported seeing "incorrect username or password" when trying to authenticate the org connection.
To resolve this you may need to change the URL in your browser that you're directed to by Gearset from "test.salesforce.org" to the specific Salesforce instance your sandbox is hosted on e.g. "csXX.salesforce.com"
Salesforce has documented this issue here including the ways to work round the problem and how to find out your sandbox instance.