How to adopt version control for Salesforce

For some folks in the Salesforce ecosystem, version control is a new (and slightly scary) concept. For others, Git is familiar — but working out how best to use it for Salesforce development isn’t completely straightforward. In this article, we’ll build up from the basics and point out some pathways for version control adoption.

What is version control?

Ever found yourself using filenames like “project-v1”, “project-v2”, “project-final”, and “project-FINAL-final”? That’s a very basic form of version control! You don’t want to overwrite and lose older versions, but you also need to keep track of which version is the latest.

Thankfully, there are version control systems (VCSs) that do this a lot better than the manual approach of duplicating files. A proper VCS is absolutely essential for managing a complex project, such as developing a Salesforce org and implementing best practices for release management. And the larger the team, the more critical the need.

The core function of a version control system is to help your team:

• track all the changes being made to your project and who made them
• see the latest version and avoid building on outdated versions
• understand your “version history” — how your project got into its current state
• recover work from past versions if needed

What is Git?

Perhaps the most widely used VCS, Git is the standard choice for Salesforce teams.

Git is a distributed version control system, in contrast with centralized systems. This means that individual developers have the entire project, including its version history, on their local machines. As a result, version control processes run faster, developers can work offline, and there’s no single point of failure for data loss.

Let’s take a look at the essential concepts for getting started with Git.

Repositories and Git hosting providers

A Git repository (or “repo”) holds all the files for a project, and Git tracks all of the changes made to the files in the repository.

In software development generally, the repo holds your source code — which is why version control is also known as “source control”. For Salesforce teams specifically, the repo holds all your Salesforce metadata — the files that represent all your configurations in Salesforce. The arrival of Salesforce DX some years ago introduced, among other things, a structure for Salesforce metadata that’s much better suited for managing in a repository.

Since Git is a distributed VCS, each developer will have that repository of metadata on their computer. There’s also a remote repository that all developers can access, which is where developers’ work gets combined. This remote repository is held on a Git hosting provider, such as GitHub, GitLab, or Bitbucket. The main Git hosting providers also offer self-hosted options, such as GitHub Enterprise.

Developers “pull” the latest version of the remote repository down to their computers, to make sure their local version is up to date. Then, once they’ve made some changes, they “push” those changes to the shared repository. These functions can be performed with Git commands in the command line interface (CLI), or you can use a click-based tool such as GitHub Desktop.

Branching, commits, and merging

Branching is a key concept for version control. At its simplest, developers can create a “feature branch” off the “main branch” of the repository. In this new branch, all the files initially look exactly as they do on the main branch. Then the developer gets to work and makes a set of changes. Perhaps they write some changes using a source-code editor like VS Code, or they’re a no-code contributor who deploys some metadata from a developer org to the Git branch.

Every so often, once a coherent set of changes has been made to the feature branch, the developer “commits” their changes. A commit functions a bit like saving those changes; it takes a snapshot of the whole repository at that particular point on the branch.

The developer is free to make changes without fear of breaking anything, because they’re developing in a feature branch and leaving the main branch unchanged. In a worst-case scenario, they can simply delete the branch and start again.

Once the work is complete, the feature branch will be several commits ahead of the main branch. It’s now time to “push” those changes to the remote repository. Then the developer opens a “pull request” to show that they want to “merge” this feature branch, with all its changes, back into the main branch. Team mates can review and approve pull requests before they’re merged.

Git branching strategies can get much more complex than this example, but the basic practice of working with Git branches is actually very intuitive once you’ve tried it.

Why adopt version control?

The main driver for version control adoption is that developers quickly begin treading on each other’s toes without it. Imagine two Salesforce developers, Anne and Ben. Anne deploys her changes to the production org; then Ben deploys his changes to production and overwrites something important in Anne’s work, breaking her feature. The next day, Anne deploys more changes to production; then Ben tries to deploy some more changes of his own, but this time he finds the deployment fails because of something Anne released.

Version control helps to avoid this pain by helping teams integrate their work streams earlier in the release process. We’ve discussed an example of one developer working in a feature branch. Of course, several developers will often be working in parallel on their own features in their own branches. Git helpfully flags any “merge conflicts” where two developers’ work has touched the same files and needs to be reconciled.

There are plenty more benefits of version control:

• It creates a full audit trail of changes
• It adds resilience because previous snapshots can be restored
• It encourages collaboration between developers
• It’s the foundation for continuous integration and continuous delivery (CI/CD) — and so it’s really the gateway to automated deployments and all the benefits of Salesforce DevOps.

How do you know if you’re ready for version control?

Any Salesforce team can begin working towards adopting version control. At the very least, it’s never too early to start learning how Git works and getting familiar with those workflows. You can always start by gradually filling a repository with metadata, and then make the important switch: placing version control at the center of your release pipeline.

Gearset’s free DevOps Assessment is a useful way to find out how your current release process stacks up, and the next steps you should consider taking.

Which version control system should you use?

As we’ve said, when teams implement version control for Salesforce, they’re almost always using Git. But which Git hosting provider is the best option for your team? There’s no wrong answer to that question — if you’re already familiar with a provider and you’re satisfied with its features, then stick with it. However, if you haven’t yet chosen a provider, GitHub is the obvious choice, simply because it’s by far the most widely used and well known.

How to implement version control for Salesforce

If you’re raring to get started, you’ll want to see how you actually use Git with Salesforce. You can see an example in this webinar video from Gearset, but bear in mind there are a lot of options for tools and processes. Every Git hosting provider looks and works slightly differently. And even where developers are using the same tools, a lot comes down to personal preference. For example, you can usually manage branches from any of the tools in your tool chain.

And when it comes to implementing version control, setting up for Salesforce DevOps success involves larger questions that need to be answered:

• Which Salesforce environments and Git branches do we need?
• How do we build up a repository of Salesforce metadata?
• Should we include all of our metadata types?
• How do we keep the metadata in Git deployable to Salesforce orgs?
• How can Git be the single source of truth (SSOT) when not all Salesforce metadata types are supported by the Metadata API?
• How do we start to fold in test automation and release automation?

Those questions go beyond the scope of this introductory article, but you can find the answers and more in Gearset’s whitepaper, Version Control for Salesforce and in the courses on DevOps Launchpad: Version Control Fundamentals and Git Branching Strategies.