Gearset and git

Module 5. Harness the power of version control through Gearset

Jason Mann avatar
Written by Jason Mann
Updated over a week ago

Learning objectives

  • Manage git connections in Gearset

  • Deploy metadata to and from version control with Gearset

  • Navigate around GitHub to view and manage configuration changes

You will need

  • To have completed Modules 1 - 4 (Gearset app fundamentals, Mastering metadata filters, Gearset's problem analyzers, Change monitoring and testing automation)

  • A free GitHub account

Getting started with git

Version control (also referred to as source control) is a well-established concept in most software languages and platforms, and is one of the key enablers for modern DevOps. At its heart, version control focuses on one core concept: tracking changes to files over time. 

In the Salesforce ecosystem, git is the de facto version control system, and is used by millions of admins and developers every day to work with Salesforce metadata. In this module you're going to use Gearset with git and see how git changes the org-to-org development flow. Gearset works with any git-based version control system, so don't worry if your company doesn't happen to use GitHub.

Version control has a range of benefits which we won't labour in this module (see the further reading section for more), but in essence, Salesforce teams who use version control release higher quality code more frequently, introduce fewer bugs, maintain better reporting and visibility, and have a better ability to roll back changes. Git is great.

Create a new GitHub repository

Make sure you have your GitHub account ready to go - you're going to need it! You can follow this guide using another git provider if you wish, but you may find it a little harder as the steps below have been written with GitHub in mind.

  • Sign into your GitHub account (via https://github.com/)

  • Click the + icon next to your profile, and click New repository

  • Name your repository: gearset-academy

  • Give it a description: My Gearset academy repository 

  • Set the repo type to: Private

  • Check the box next to Initialize this repository with a README

  • Click Create repository

You now have a new, empty repository to work with. A repository is a place to store files - in this case, you're going to store some sample Salesforce metadata. Any changes to any files in a repository are automatically tracked and kept in the audit history.

The next step is to connect this repository to your Gearset account.

GitHub and Gearset

  • Open a new tab in your browser and sign into your Gearset account

  • From the menu, click Source control and services

  • In the list of connections, click + Connect to GitHub

  • Follow the OAuth flow to grant Gearset access to your GitHub account

  • Now it's time to populate the repository with some metadata. On the Compare and deploy page, select your source org as the source

  • For the target, click Source control. If the dropdown isn't already on GitHub, select that from the list

  • You'll see a list of all repositories your GitHub account can access. If you've created a brand new account for this module, you'll only see your new gearset-academy repository; if not, find that from the list and select it

  • In the branch selector, check main is selected

  • In most cases you wouldn't want to push changes straight to your main branch in git - it's analogous to making changes directly in your production org. But since you're about to do some initial setup, you can have a free pass this one time

  • Select the Compare all metadata filter

  • Click Compare now

  • Select all the new items (which will be everything), and click Next

You may see a few problem analyzers appear at this point, suggesting that you exclude some components from your deployment. This is one of those cases where despite its best intentions, you're going to want to ignore the suggestions. 

If you look at the messages, they're flagging that you're attempting to deploy standard objects and applications which aren't deployable to a Salesforce org. Normally, removing them would be the correct solution, but because this deployment is using GitHub's API things should go fine. 

  • Ensure you deselect all the problem analyzer suggestions, click Next and then Continue to summary

  • Give your deployment a descriptive friendly name, such as: Initial repository seed

  • Enter the deployment note: Initial deployment with Gearset. This deployment note will become the commit message in your GitHub repository

  • Click Commit changes. Notice that the option to validate is disabled as the target is not a Salesforce org, so there is no way to run a validation

  • Once the deployment completes, go back to your tab with your repository open in GitHub, and refresh the page

  • It's full of metadata! You can see the commit message displayed next to each file and folder that you added

You've now got a version control repository which mirrors your source org. Please know that as your repository was empty, Gearset will use the SFDX format for the initial commit(see this article for details). Try running a comparison between your source org and your repository and you'll find them (almost, see this article for more detail) exactly in sync.

Time to make some more changes in the source org. Instead of deploying them straight to the target org, you're going to go via version control.

Working with branches

  • Log into your source org and add a new field to the Case object

  • Type: Text

  • Field label: Case Description

  • Length: 250

  • Field name: Case_Description

  • Description: A description for the case background and why it was opened

  • Help text: Enter the case background information here!

  • Set the field-level security to so it's only visible to the Custom: Support Profile and System Administrator profiles

  • Leave the page layouts on their default values, and click Save

Time to get the new field into version control. With Gearset, the process for deploying to git is exactly the same as to an org - it's one reason why the workflow is so easy for whole teams to adopt.

  • Back in Gearset, go to the Compare and deploy page and select your source org as the source of the comparison

  • For the target, click Source control and confirm you've selected your gearset-academy repository

As mentioned before, normally you shouldn't deploy changes straight to your main branch, so the first thing is to create a new branch to deploy the changes into. A branch is an independent copy of all the files in your repository - changes made in one branch do not automatically affect other branches.

  • Underneath the branch dropdown, click Create new branch from main

  • Name the branch: case-description

  • Click Create branch

  • Gearset will now create your new branch and automatically select it

  • Select the Default comparison metadata filter, and click Compare now

  • The resulting comparison will have 5 changed items (the layouts which have had this field added to them) and 2 new items (the field and its permissions). Select them all

  • Click Next to get to the summary of items to deploy

  • Add a deployment note / commit message: adding new case field

  • Deploy the changes

  • Once the deployment has completed, leave Gearset on the deployment successful page. In your browser, switch back to your GitHub repository tab and refresh the page. GitHub will highlight that your branch has new changes - handy!

  • Click the case-description words in bold to switch to the branch. Notice that the number of commits has now changed from 2 to 3 as you're now looking at your newly updated case-description branch

  • Click 3 commits to view the commit history for the branch

  • The top commit is your change just now. Click on it to view the changes

  • GitHub will now show you all of the changes to your configuration that this new field is adding - 8 changed files with 44 additions in a few clicks

Your new field and its associated changes are now in version control. Take a minute to scroll through this page to see all the changes you've just deployed into version control with Gearset.

The next step is to get these changes from your case-description branch into the main branch. To do this you'll need to merge the two branches together in what's called a pull request. You can open a pull request from within GitHub or Gearset.

  • In Gearset, on the deployment successful screen, click Create pull request. (If you've closed this page, you can get back to it from the deployment history page by clicking View details)

  • Gearset will pre-fill the name of the pull request based on the branch name

  • Confirm the target branch is: main

  • Enter a short description: Adding the new case description field

  • Click Create pull request

  • Once the pull request has been created, click the link to view it in GitHub

  • You'll be redirected to GitHub, to the open pull request

Pull requests are the code review process in GitHub. They provide a framework for any changes to be inspected, tested, commented on, and approved for release. Click on the Conversation, Commits, and Files changed tabs to see the information about this pull request. You'll see that the files changed is the same list as you saw earlier when looking through the commit history in your branch.

This is the point where you would normally assign this change request to a colleague for review and approval, but in this case you're going to go ahead and approve it without review. This will cause GitHub to merge your new changes in the case-description branch (the new field) into the main branch to bring them both in sync.

  • Click Merge pull request and then Confirm merge

  • Once it's merged, click Delete branch. This will remove your feature branch as it's no longer needed. Your changes have been collected in the main branch, and deleting old branches keeps the repository clean and easy to navigate. You can always restore the branch at a later time if you need to.

Deploying from git to your target org

So far you've made a change in your source org, created a branch in GitHub and deployed the change into it, and merged the branch into main. Main is now totally up to date with your source org. The final step is to deploy the new field from GitHub to your target org. This flow is exactly the same in Gearset as before, you're just going to use GitHub as the source and your target org as the target of the comparison.

  • Back in Gearset run a comparison between your GitHub repository on the main branch as the source of the comparison, and your target org as the target

  • Select the 3 new items to deploy (this will include your previously undeployed custom field permissions for the DiscountRate field which you may as well deploy now to ensure that field has the correct settings)

  • You will have a number of changed and deleted items which you shouldn't deploy. Recall that your source and target orgs weren't totally in sync due to some setting differences. This repository is mirrored to your source org, so it will have the same differences

  • Add a deployment note and description, and deploy the changes to your target org

  • Log into your target org and check the Case object - you should find the new field is present, and if you check the field-level security it will only have access from the Custom: Support Profile and System Administrator profiles

Congratulations, you've stepped through the development lifecycle with version control and Gearset!

Further reading

Did this answer your question?