With Gearset, you can compare and deploy metadata contained in source control repositories with your Salesforce orgs. To make this process as smooth as possible, there are a few general best practices to follow.
Please note, this article is based on the existing Metadata API format. Repositories in the DX format have a different structure.
Want to know how to run a comparison from source control? Read our feature guide for more information.
Initialise your repository first
Gearset can't deploy your metadata to a totally blank repository. You'll need to initialise your repository first and create a branch to deploy to.
Structure of the metadata in your repository
Metadata in source control should be in the same format as you use for Ant or Eclipse deployments. Within a branch, each metadata object type should sit within its own folder. You can place all of these folders within a single
unpackaged folder if you wish, but you should not create a nested folder structure.
Working with package.xml files
If Gearset detects a valid
package.xml file in your source repository, by default we will use that to filter your comparison results. This will build on top of the comparison filter you have selected in the app. This can be a great way to reduce noise when comparing orgs and source control, but it can sometimes mean that you may not see all the metadata you expect when running a comparison.
You can turn off filtering by package file as part of your comparison configuration by un-checking the box underneath the branch (see more in this article).
If you've run a comparison and you're not seeing metadata you would expect in the results, check if a package.xml file exists in your branch. If it does, confirm that it is listing all the metadata types you wish to see, or disable the package filtering option.
Commit messages when deploying to source control
When running a deployment into your repository, Gearset can enter a commit message for you. Any text you enter into the deployment notes section in the pre-deployment summary will be included as your commit message. Your team owner can also make deployment notes compulsory, helping to make sure your team maintains a clear record of every deployment.
What source control systems does Gearset support?
Gearset currently supports OAuth connections to GitHub, GitHub Enterprise, Bitbucket, Bitbucket Server, GitLab, Azure DevOps Git (previously known as VSTS or TFS), and AWS CodeCommit. This includes branch level support for all repos.
You can also add a connection to any git-based VCS that Gearset can connect to, via a custom git connection. See more about connecting to VCS.