Whether you're setting up a Git repository for the first time, or just want to create a new one for use with your Gearset account, you can easily do so by following this guide.

Choose a Git provider

Gearset can connect to any Git-based source control system using a username/password. However, when possible, we would suggest using a Git provider that you can connect to via OAuth.

The full list of providers that support this authentication method are listed in this article. In our experience, the three most popular providers are:

  • GitHub

  • BitBucket

  • Azure DevOps Git

Create a repository

Once you've created a Git account, you will need to create a repository. The exact instructions vary with each Git provider, but in GitHub it's as easy as clicking New from the Repositories tab:

Make sure that you initialise the repository with a README file, as this is necessary for Gearset to then detect your repository. Adding a README will also automatically set main as the default branch in your repository.

Invite any teammates who will interact with your source-driven release pipeline inside Gearset to access your new repository. They will need the appropriate Write access. Each user should have their own Gearset account, on a central Gearset team, and should authorise their own Git credentials.

You might also consider setting some branch protection rules, although this isn't a hard requirement. Larger teams, for example, may want to restrict who can make changes to certain branches. Setting this up varies slightly depending on provider; this Github article is a comprehensive guide. Branch protection rules can be used in parallel with Gearset's org delegation feature; an effective way to gate releases.

Configure the deployment

After you've created your empty repository, you need to populate it with metadata. Best practice states that your main branch in your Git repository should be your source of truth, which is why you should populate this branch from your Production org in order to capture and track the latest changes.

You can run a standard comparison using your Production org as the source, and your newly created main branch as the target.

What metadata should I deploy to source control?

It may be tempting to run a Compare all comparison and deploy all of your metadata from Production to your main branch. However, if you're just getting started with source control, you may find the number of changes being tracked overwhelming for you and your team. You may also end up with a large amount of metadata types in source control that you never actually make changes to, which will bring you little functional benefit.

Because of this, we recommend starting with a smaller sub-set of metadata types that your team commonly make changes to. You can use the Default comparison filter (64 metadata types) as a starting point, and make changes to this filter based on which types you actually modify. For example, if your team don't edit apex classes, you should remove these from your filter.

It's far easier to add in metadata types as and when you start modifying them, than having to deal with an overly large and complicated repository from the get-go.

Making the deployment

Once you've set your metadata filter, run the comparison and select All components:

Proceed to the next page, where Gearset will run its problem analysis step.

Important: It's likely you'll see some problem analyzers appear at this point, suggesting that you exclude some components from your deployment. If you look at the messages, some will likely flag that you're attempting to deploy standard objects and applications which aren't deployable to a Salesforce org. Normally, removing these components would be the correct solution; but for this deployment we want them in the repository, to give us an accurate source-of-truth.

Use your best judgement here: check each problem analyzer individually, and consider whether following the advice would impede creating an accurate mirror of Production. It's likely that, despite the problem analyzers' best intentions, you're going to want to unselect many of the recommended fixes.

Once you've worked through the problem analysis, continue to the next page. You can add some notes to the deployment, and then click Commit changes:

And voila, you have now created your main branch, with an up-to-date copy of your Production metadata! You can now use Gearset to create branches, open PRs, and even validate PRs before they are merged.

Your team can now decide which branching strategies to use - we're personally fans of the feature branch model. You can also browse plenty of other branching strategies in our free DevOps launchpad, with a dedicated course on choosing the right branching strategy for you and your team.

Things to keep in mind

  • Metadata deployed to an empty repository will be deployed in the newer SFDX format, as per Salesforce's latest guidance.

  • When deploying completely new items, you will not be able to select specific sub-components (e.g. custom fields) for deployment. You will need to deploy the entire object.

  • You may expect your newly created main branch to show no differences when compared against Production, but read this article to find out why this often won't be the case.

  • Some teams may also want to use source control as a backup solution for their metadata, but this provides a technical obstacle to those not familiar with Git. We'd recommend setting up a change monitoring job in Gearset instead, which can provide the same backup capabilities, alongside the ability to roll back or re-sync lower environments and branches.

  • Gearset will automatically create the sfdx-project.json file in your new repository, and set the API version to match the initial commit. You will need to manually update this version as newer API versions are released by Salesforce.

Should I source control managed packages?

In general, we'd recommend following the same guidance for managed packages as you do for any other metadata type: if you're making modifications to your managed package metadata, you should put it into source control.

However, even if you're not making any changes to your managed package metadata, it might still be useful to source control the installed package metadata type. This metadata type represents the version of your managed package, and can be deployed from source control. This can help you to efficiently install the same managed packages across environments, without the need for manually installing them in each org.


We hope this article helps guide you through the main steps of creating a source control repository, but if you have any questions, please get in touch via the in-app chat. You can also use the in-app chat to book a free consultation with one of our DevOps experts to discuss the most suitable Git workflows for you and your team!

Did this answer your question?