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 accomplish this by following this guide.

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.

In our experience, the three most popular providers are:

The full list of providers that support this authentication method are listed in Managing source control connections in Gearset. After creating a Git account, you will need to connect it to Gearset, following the steps in the guide above.

Once you've created a Git account, you will need to create a repository. The exact instructions vary with each Git provider, so we'll use GitHub as the example for this walk-through. In GitHub, begin by clicking New repository from the top navigation dropdown menu:

Make sure that you initialize the repository with a README file by checking Add a README file, as this is necessary for Gearset to then detect your repository. This will also automatically set main as the default branch in your repository. Next, click, Create repository.

After you've created your new repository, invite the teammates who will interact with your Gearset pipeline to your new repository. Go to Settings > Collaborators > Add people and add your team members. If using a different Git provider, make sure to assign each team member Write access so Gearset can interact with the repository (In GitHub, Collaborators have Write access by default). In Gearset, please ensure each user has their own Gearset account, is on the same Gearset team, and has authorized their individual Git credentials.

You might also consider setting some branch protection rules. Although setting branch protection rules is not required, larger teams, for example, may want to restrict who can make changes to certain branches. Setting this up varies by provider; GitHub's guide, About protected branches in their Creating and managing repositories page is a good place to start. Another strategy to gate releases natively, in Gearset, is to make use of the org delegation feature to restrict Gearset team members' access.

You have now created an empty repository. Next, you need to populate it with a baseline of metadata. Our version control best-practices states that your main branch in your Git repository should be your source of truth. As such, you should populate your main branch from your Production org in order to capture and track the latest changes.

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

We recommend starting with a smaller sub-set of metadata types that your team commonly makes changes to. You can use the Default comparison (63) filter as a starting point, and make changes to this filter based on which types you regularly work with.

It may be tempting to use the Compare all (258) filter and deploy all of your metadata from Production to your main branch. Not only can this lead to validation errors, if you're just getting started with source control, you may find the number of changes overwhelming. You may also end up with a large amount of metadata types in source control that you never actually make changes to. As such, we recommend Splitting a complex deployment into stages.

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.

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, while allowing your team to become comfortable easing into automation. For larger teams, or those with advanced branching models, this lightweight approach may not be suitable.

For those wanting to master the basics, we recommend at minimum including these component types: 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.

Once you've set your metadata filter, run the comparison and select All items. Click Next , to proceed to the Problem analyzer page.

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. Despite the problem analyzers' best intentions, it's likely you're going to want to de-select many of the recommended fixes.

Once you've worked through problem analysis, continue to the Pre-deployment summary page.

You can add some notes to the deployment, and then click Commit changes.

And voilà, you have seeded 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 strategy 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 learn about other branching strategies in DevOps launchpad, by completing our free course on Git branching strategies to assist in choosing the right fit for your team.

This document can help outline which metadata types you may need as a team:
​What metadata types should I include for Gearset pipelines?

If you are using the Gearset CPQ deployment solution, you can deploy config data to source control using Compare & Deploy.
​

We recommend storing all CPQ configuration data in a repository. This practice helps mitigate issues both in the immediate, and in the long term. For example, versioning CPQ config data can avoid dependencies from being missed in your deployments.
​

If there is a large amount of config data, you may need to split the deployment to your repository into multiple steps.

For deciding whether to put managed packages into your repository, follow the same guidelines as you would for other metadata types:

Even if you do not modify the managed package metadata, it’s still beneficial to track the Installed package metadata type. This metadata represents the version of your managed package. Using Gearset, you can deploy managed packages and their versions between environments from source control. This saves time by avoiding manual installations in each environment.

Following these steps will ensure you have both customizations and the version details (Installed Package) tracked in your repo.

For more details around the practicalities of versioning managed packages, see Should I source control managed packages? If you choose to version managed packages, we also recommend reading Comparing managed package metadata with Gearset.

We hope this article helps guide you through the main steps of creating a source control repository. If you have any questions, please feel free to get in touch via the in-app chat, or check out our Help Center.