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.

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:

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

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 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.

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.

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 sub-components), 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.

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 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.

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!