Skip to main content
How to set up a new source control repository

A practical guide to setting up a new source control repository, ready to use as the source of truth in a Gearset release pipeline

Toby Newman avatar
Written by Toby Newman
Updated over a week ago

Whether you're setting up a Git repository for the first time, or 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

After creating a Git account, you will need to connect it to Gearset using these steps.

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 initialize 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 authorize 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 can be a good place to start. Branch protection rules can be used in parallel with Gearset's org delegation feature; an effective way to gate releases.

Configure the baseline deployment - For a pipeline specific repo, see here

After you've created your empty repository, you need to populate it with a baseline of 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?

Which we discuss in detail in a separate document.

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 (63 metadata types) as a starting point, and make changes to this filter based on which types you actually modify.

For example: my team has recently started building community sites as part of our new Salesforce Experience Cloud initiative. We decide it would be a good idea to version any Experience changes being built, so I add Experience bundle to the default filter:

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

What about a lightweight approach? - Some teams choose to start with a more limited selection of metadata when setting up their repository. This can make it easier to manage a repository, especially if you're just getting started with source control or CI/CD. It'll allow you to build up your repository's metadata over time as you commit features, whilst allowing your team to become comfortable with the way of working and ease into any automation. For larger teams or those with advanced branching models, the lightweight approach may be unsuitable.

For those considering a lightweight rollout to help them master the basics, we recommend including these component types at a minimum: Apex class, Apex component, Apex page, Apex trigger, Approval process, Custom application, Custom object (and all subcomponents), Custom permission, Custom tab, External data source, Flow, Layout, Muting permission set, Permission set, Permission set group, Profile, Global value set, Profile, Standard value set. This list covers the core metadata types, while also ensuring you have the requisite components needed to successfully version any profile, permission and layout changes.

Important: Also consider whether you need to seed managed packages into your repository. If this is the case, read the advice detailed below.

Setting up a repo for Gearset pipelines

Configure and save a custom metadata filter that includes all the metadata types that you're likely to work on as a team. This document can help outline which metadata types you may need as a team:
What metadata types should I include for Gearset pipelines?

Using that newly created filter, run a comparison between Production and your Main (or Master) branch and commit everything into the Main/Master branch. Be sure to deselect all problem analysers.

Once this has been deployed, create a branch for each long-lived environment in your Pipeline (i.e. UAT branch for UAT org, Preprod branch for Preprod org etc).

Finally, set up the repository configurations that you're needing, i.e. user permissions, branch protections, reviewers etc.

What CPQ Config data should I deploy to source control?

If you are using Gearset's CPQ deployment solution, you can deploy config data to source control.

Storing all CPQ configuration data in a repository is generally a recommended approach for users. This practice helps mitigate potential issues, both in the immediate and long term, such as avoiding the occurrence of missing dependencies.

It is important to note however, that if there is a large amount of config data then, you may need to split the deployment to source control into multiple steps.

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 voilà, you have 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. For those new to source control, the feature branch model is a great place to start. Teams requiring more nuance in their approach to branching should check out Gearset Pipelines. 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 subcomponents (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?

Generally, 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. If you don't make changes to packages, there may be little practical benefit to having them in your repo.

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 to environments. This can help you to efficiently install the same managed packages across environments, without the need for manually installing them in each org.

For more details around the practicalities of versioning managed packages, see this detailed doc.

If you do indeed choose to version managed packages, we also recommend you to read this doc.


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?