If you have Compare & Deploy and haven't yet run a deployment, this guide walks you through everything from connecting your orgs to deploying your first set of metadata changes.
Step 1: Install the Gearset Connected Apps
Following a recent Salesforce security policy update, you'll need to install the Gearset Connected Apps in each org you want to use with Gearset. This is a one-time step per org and takes less than a minute — you'll just need a Salesforce System Administrator to go to the Connected Apps OAuth Usage section in Salesforce Setup and click Install next to the Gearset apps.
For full instructions, including what to do if the apps aren't showing in your org yet, see How to install the Gearset Connected Apps.
Step 2: Connect your orgs
Before you can compare or deploy, you'll need to connect your Salesforce orgs in Gearset.
Go to My connections in the left-hand side menu, or add connections directly on the Compare and deploy page. If you've already connected your orgs, skip to Step 3.
Further reading:
Step 3: Configure your comparison
Log in to Gearset and go to Compare and deploy under Metadata deployments in the left-hand menu.
Select your source and target: Under Choose comparison source location, click Salesforce organization and enter the username for your source org. Repeat for your deployment target. Once both are selected, the Compare now button will become enabled.
Step 4: Configure your metadata comparison filter
When running a comparison, Gearset compares the most common metadata types between your source and target by default — Custom Objects, Profiles, Permissions, Apex code, and more. This is called the Default comparison.
If you want more control over what metadata is compared, you can select a different filter or create a custom one before running your comparison. To learn more about metadata filters and how they work, see this support article.
Step 5: Select the metadata items you want to deploy
Once retrieved, you'll see what's changed, when, and by whom — without needing to diff XML manually. For a full guide to reading the results, see Exploring comparison results.
From the comparison results, tick the checkbox next to each metadata item you want to include in the deployment. To see everything you've selected at a glance, navigate to the Selected items tab.
A note on dependencies: Gearset surfaces related items and dependencies in a tree view. Expand any item using the small arrow next to its name to see:
Components — constituent parts of the item (e.g. custom fields within a custom object).
Depends on — items your selection relies on; you may need to include these too.
Profiles and permissions — related field-level security or profile changes.
Used by — items that depend on what you're deploying.
Gearset automatically breaks profiles into their constituent components, so you can deploy just the parts you need rather than an entire profile.
Step 6: Review Gearset's problem analysis
Once you've made your selection, click Next. Gearset will check for missing dependencies or other issues that could cause the deployment to fail, and suggest fixes.
You can accept the suggestions, go back to adjust your selection, or continue without making changes — though following the recommendations will give you the best chance of a successful deployment.
Step 7: Review the pre-deployment summary
Before deploying, you'll see a Summary of items to deploy showing your selected metadata, the difference type for each item, and your source and target orgs.
From here you can:
Add deployment notes to record why you're running the deployment (e.g. a sprint name or feature release).
Download the package to inspect the raw XML if needed.
Validate the deployment to do a check-only run — this tests your components against the target without applying any changes.
Associate a ticket from Jira, ADO Work Items or Asana, and change the item’s position on the kanban.
Deploy now to go ahead.
You can also use the arrow next to Deploy now to schedule the deployment for a later date or set a specific Apex test level.
Step 8: Run the deployment
Click Deploy now to begin. Gearset will upload the package to Salesforce and queue it for release. Depending on the number of components and the tests running in your org, this may take a few minutes — but you can safely navigate away and check progress in Deployment history.
When the deployment finishes, you'll see a summary on screen and receive a copy of the deployment report by email.
Should you need to, you can also roll back the deployment partially or in full from the summary page or deployment history.