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 uses secure OAuth to connect to your orgs. There are 3 ways to do this:
test.salesforce.com - This is used to connect sandbox organizations which have not enforced custom domain login.
login.salesforce.com - This is used to connect Production or Developer Edition organizations which have not enforced custom domain login.
Custom Domain
The Salesforce user you connect to your orgs must have the Modify all data permission in order to run comparisons and deployments through Gearset.
Note: We have added the ability to add connections to Salesforce orgs hosted on Alibaba Cloud - this is currently in pilot and details can be found here.
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
You can add an org from either the Compare and deploy page or the Salesforce orgs page in the Gearset app.
Select the appropriate method for the org you're connecting to. If you select
Custom Domainyou will be asked to enter the custom domain to use.Turn on or off the Team-Shared toggle, based on whether or you you require this connection to be team shared.
Click Connect. You'll be redirected to salesforce to log into your org.
Click
Allowwhen prompted, to grant Gearset access to the org via OAuth.
If Custom Domain is selected
When you return from Salesforce 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.
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.
Note: Your org admin can turn off authentication against login.salesforce.com or test.salesforce.com and enforce login via the orgs custom url. If this is the cause then please use the Custom Domain option to connect your org.
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.