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.

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, Flow definition, Layout, Muting permission set, Permission set, Permission set group, Profile, Profile Password Policy, Profile Session Setting, 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, you'll need to follow the two-step process detailed below.

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?

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

If you decide to source control your installed package metadata file(s) and the metadata components belonging to your package(s), you'll need to undergo a precursor step before making the main metadata deployment. Due to some prerequisites in how the Metadata API understands packages, you need to deploy installed package as a separate deployment, before deploying the actual components of the package. The installed package houses the version of your package, which needs to be in place in your repo before we can successfully detect the components belonging to the package. You should:

  1. Deploy the installed package metadata only into your new repository, before seeding any other metadata types. Do not be tempted to deploy any other metadata types until installed package is successfully seeded into the repository. To do this, select only the installed package(s) for your desired packages in the metadata filter, and deploy these to your repository.

2. Once you have successfully deployed the installed package(s), you can now begin the main deployment job (in the main article, above). Just remember to include the managed package(s) in your comparison filter:

Questions?

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?