Learning objectives

  • Understand the core Gearset workflow

  • Add Salesforce org connections

  • Compare and deploy changes between two Salesforce orgs

  • Roll back a deployment

You will need

  • To have read The Gearset academy introduction module

  • Source and target orgs as defined in The Gearset academy

  • A Gearset account with an active trial period or subscription

An introduction to Gearset

Gearset is different to other development tools for Salesforce. We've taken a unique approach which lets you visualize, understand, and manage your changes in a simple yet powerful way. 

As with any new tool, there will be a few things to learn on your way to mastery. In this module you'll build an understanding of how Gearset operates and step through the core workflow.

The core Gearset workflow

Almost every metadata deployment in Gearset follows the same core workflow:

  1. Compare metadata between two environments

  2. Select metadata items to deploy

  3. Check for missing dependencies

  4. Validate/deploy changes

  5. Deployment recorded in history

This workflow applies to automated continuous integration (CI) jobs as well as standard deployments. Automated jobs will simply run through all of these steps for you and display the end result. 

Before you get started with the practical steps, let's take a look at each of these stages in more detail.

1. Compare metadata between two environments

Gearset allows you to compare any two environments and see the configuration differences between them. This is the starting point for building your deployment: once you know what's different, you can choose which of the changes you want to deploy.

Whether that's Salesforce orgs, your version control system, or even files on your local machine, you can compare them all with Gearset.

Some common comparisons that you might run are:

  • Your developer org and your integration sandbox - to see the changes you've been working on and deploy them for testing

  • Your developer org and your git repository - to commit changes you've been working on into your version control system

  • Your git repository and a scratch org - to quickly test changes against a known testing environment

  • Local files you've been working on in an IDE and your git repository - to commit the changes so they're tracked in version control

  • Your full copy sandbox and production - to release changes that are ready for your end users to start using

  • Production and your git repository - to capture hotfixes back into version control

Gearset supports any Salesforce org, and any git-based version control system. When you run the comparison, Gearset will show you exactly what metadata differences there are between your source and target.

2. Select metadata items to deploy

Once you know what's different between your environments, you can choose which components you want to select for deployment. Deploying the changes moves them from source to target, to bring both environments in sync.

Checking the box next to the name of a metadata item will select it, and add it to your list of changes to deploy. This is broadly similar to how you'd build a change set. You can search and filter for metadata items by name or type using the filter box.

In the screenshot below, three items have been selected for deployment, as shown by the blue ticks next to their names.

3. Check for missing dependencies

As part of the pre-deployment preparation, Gearset automatically scans through your selected items and looks for any missing dependencies or other issues with your package.

This happens outside of Salesforce, and is part of the power that Gearset provides through its deep understanding of your metadata. If the app detects any issues, it will suggest changes that you should make to your deployment package to make it more likely to successfully deploy.

For example, say you want to deploy a new Apex class, CustomSiteRegisterController, and this class depends on a couple of other objects and fields. If you select that class to deploy, Gearset will scan its XML and alert you if you've not selected its dependent components. It'll then suggest that you include those dependencies in your deployment. This will make the deployment more likely to succeed.

Checking the boxes for each problem analyser will accept the suggestion, and make the proposed changes to your deployment package. If you don't want to include any of the suggestions, simply un-check the box next to it.

4. Validate/deploy changes

Now your deployment package is ready to release. Gearset will show you the summary of the components that are going to be deployed, including anything added as part of the dependency analysis. If you want to inspect the changes in more detail, you can download the package file to view the raw XML.

When you're ready to go, you can kick off the deployment and get that metadata released to your target environment. Gearset will upload the selected metadata to Salesforce (or git), request it validates and applies the changes, and let you track the status in real time.

5. Deployment recorded in history

Beyond helping you deploy changes, Gearset is also a powerful reporting and audit tool. Any deployment you make will automatically be stored in the app, with full reports, details, and email notifications. You can see deployments made by any of your team members and quickly search and filter the results.

The deployment history is also where you perform other actions such as rolling a deployment back or cloning it to another environment. More on that later in this module.

Now that you're familiar with the core workflow, it's time to dive in and try it out for yourself!

Add source and target org connections

Before you can run any deployments with Gearset, you'll need to connect at least two Salesforce orgs. Adding a connection is quick and secure, and allows Gearset to retrieve and deploy metadata to that org using the Salesforce metadata API.

Gearset authenticates against orgs using the industry-standard protocol for authorization, OAuth 2.0. This means Gearset does not access or store your username and password.

  1. Open the Gearset app menu, and select Salesforce orgs

  2. Click Add new organization... 

  3. Select Salesforce authentication as the authentication method

  4. Enter your source org username

  5. Select Developer organization as the org type

  6. Click Authorize

  7. Log into your org through Salesforce

  8. Click Allow on the OAuth access request page

  9. Give your org connection a friendly name (e.g. Source org for your source org, and Target org for your target org)

  10. Repeat steps 2-9 for your target org so that you have both org connections saved in Gearset

Compare source and target orgs

Now that you've connected your two Salesforce orgs to Gearset, it's time to compare them to see what's different.

Gearset allows you to easily see differences in any two orgs' metadata before you deploy any changes between them. This ensures you know exactly what state both orgs are in and allows you to pick exactly what you want to deploy. No more forgotten components or accidental overwrites.

  1. Open the Gearset app menu, and select Compare and deploy

  2. Under the source metadata location, click Salesforce organization

  3. Click the username dropdown arrow and select your source org (you can also type your username or the friendly name into the box)

  4. Repeat the process for the target metadata location, using your target org

  5. Ensure the Metadata comparison filter is set to Default comparison

  6. Click Compare now

Gearset will now retrieve the metadata from your source and target orgs. It will then display the results of the comparison between them, highlighting any items that are different in the results grid. 

The top half of the screen lists the metadata items that have been retrieved. Clicking anywhere on the row of an item selects it. The lower half displays the line-by-line difference between the source and target for any selected metadata item.

You might think that these two orgs might be totally identical, given that they were both just created. Not so! You'll see a number of metadata items which are different between your two orgs. For example, you're likely to see several assignment rules and settings which are different - they reference the unique usernames in each org. 

This is an important lesson. No two Salesforce orgs will ever have totally identical metadata. Fortunately, Gearset has several ways to narrow down the metadata in your comparison so you can see only what you're interested in - you'll cover that in more detail in the next module.

For now, it's time to make a change in Salesforce and see how that is represented in Gearset.

Make a change in your source org

  1. Keep your comparison in Gearset open. In a new tab in your browser, log into your source org in Salesforce via https://login.salesforce.com

  2. Open the Setup menu and navigate to the Object Manager

  3. Select the Account object, and select the Fields & Relationships tab

  4. Find the SLA field and open it

  5. Under the Values section, find the Platinum value and click Del

  6. Confirm the deletion and click Save

  7. In Gearset, click Refresh comparison, then on the resulting dialogue, click Refresh comparison

  8. Gearset will now retrieve the most up-to-date versions of the metadata from your orgs and display the updated results

  9. Once the refresh has completed, you will see a new metadata item appear in the Changed items tab in the result table - the SLA field on the Account object

  10. Select the Account.SLA custom field and scroll down the XML viewer to see the value displayed in gray in the source and red in the target - this means it has been removed in the source org but still exists in the target org

This simple example demonstrates how changes you make to your org configuration are represented in Gearset. Any metadata changes can then be deployed to a target org to get them both in sync.

Add a new field and permissions

Time for a bit more practice. In your source org, add a new field to the Account object and refresh the comparison in Gearset to find it in your results.

  • Field type: Checkbox

  • Label: Platinum user

  • Name: Platinum_user

  • Description: Does this customer have our platinum level of support?

  • Set the profile visibility to: Visible for the Contract Manager, Custom: Sales Profile, Custom: Support Profile and System Administrator profiles

  • Uncheck all page layout assignments

Once you have saved your field, refresh the comparison in Gearset. You will now see two items appear under the New items tab.

  • Account.Platinum_user custom field item. This represents the new field itself, along with the description and other settings

  • Permissions for Account.Platinum_user__c custom field permissions item. This represents the field level security additions to each profile that define access to the field - in here you will see references to all four profiles you set the visibility for in Salesforce. Gearset helpfully combines all of these changes into a single item so you can deploy them all with a single click.

Select each item in turn to see how the metadata for your new fields is represented in Gearset. Note that every line is green as these fields are entirely new to the source org.

Deploy the changes to your target org

So far, these changes only exist in your source org, so it's time to deploy them to your target org. Once you've selected the items you want to deploy, Gearset will build your deployment package and give you a chance to review and comment on the changes before you deploy them.

  • From the comparison results in Gearset, check the boxes next to your three changed items

  • Hint: the Account.Platinum_user and Permissions for Account.Platinum_user__c will be in the New items tab, and the Account.SLA item will be in the Changed items tab

  • Click the Selected items tab to confirm all three items have been selected for deployment

  • Click Next

  • Confirm that the three items appear in the summary of items to deploy

  • Hint: you will also see a number of other items in this list; in order to deploy the individual field level security values over the Salesforce metadata API, Gearset must also include the parent profile that they belong to, and the parent custom object must be brought in to deploy the custom field changes

  • Give your deployment a friendly name (e.g. Adding plat user field and SLA edit)

  • If you wish, you can enter additional deployment notes to provide more detail on what you're deploying (e.g. Removing the old platinum SLA value, and new field to track platinum users on the Account object)

  • Click Deploy now, and then Deploy in the window that appears

Gearset will now deploy your selected changes to your target org. You'll be able to see the live status of the deployment as it happens as well as a link to view the deployment status in Salesforce.

Once the deployment completes, log into your target org in Salesforce and you'll find your new field and value have appeared on your Account object! It's as easy as that. 

You'll also get an email confirmation from Gearset with a summary of the changes and a deployment report. 

View deployment history and perform a rollback

Gearset saves a full history of every deployment you make in the Deployment history page. From here, you can view details of any previous deployment, download reports, view what was deployed, and quickly deploy the same changes to other orgs.

But what if your new changes were causing problems in the target org - perhaps you weren't supposed to delete that picklist value? With Gearset, you can easily roll deployments back from a snapshot of the target taken during the original comparison. This allows you to quickly restore it to its previous state.

  • From Deployment history, select the deployment you just ran to expand it out (it will be the top result in the table)

  • Click Roll back, then Start rollback comparison

  • Once the comparison completes, you'll see a comparison table much like before, only this time you're looking at the target org at two points in time: as it was before this deployment, and as it is right now

  • Both fields from the previous deployment will have their checkboxes ticked

  • On the Selected items tab, uncheck the Account.Platinum_user field - it will disappear from the list

  • Click on the Account.SLA field

  • Scroll down on the XML viewer and you'll notice that the Platinum value is now shown in green; by deploying this rollback, you're going to re-add the value that you deleted in the previous deployment

  • Click Next

  • Confirm that only the Account.SLA field and the Account custom object are in the summary of items to deploy, add any deployment notes, and click Deploy now

Gearset will now roll back just that SLA field change in your target org. The other changes you deployed - the new field and associated FLS - will remain intact.

Once the deployment has completed, log into your target org and you'll find the Platinum value is has reappeared. The rollback deployment will also appear in your deployment history in Gearset, and you'll receive another email confirming the deployment.

Congratulations! You've now completed this module. You've covered the core Gearset workflow, how to add org connections, compare them, make and deploy changes, and selectively roll a deployment back.

The next module introduces metadata filters and how to use them to control what metadata you see in your comparison results.

Further reading

Did this answer your question?