Gearset's repo dependency cleaner - keep your metadata deployable

Gearset has always championed the use of source control within Salesforce DevOps. We make it easy for teams to build a release process around source control, and it’s been great to see more and more teams reaping the rewards of doing just that. What’s more, we also help you to overcome potential difficulties that come from using a version control system (VCS). Gearset’s repo dependency cleaner fixes one such difficulty: metadata in a Git repo becoming undeployable.

Metadata in your Git repo can become undeployable

Undeployable metadata is just metadata that you can’t deploy to an org via the Salesforce Metadata API. Whenever you see a deployment error message (or several!), your metadata is undeployable until the problems have been resolved.

But you’d have no problem deploying this same metadata to a Git branch; your VCS will happily accept whatever metadata you throw at it. So you can easily deploy changes to a repo that can’t actually be deployed to a Salesforce org. And you won’t normally find out that this metadata is undeployable until you try deploying it from your repo to an org, at which point you’ll hit a bunch of error messages.

How Gearset’s repo dependency cleaner helps

Gearset’s repo dependency cleaner keeps your metadata deployable by deleting items with missing dependencies - a common cause of deployment failure - from your repo. Some of Gearset’s problem analyzers are designed to prevent items being left with missing dependencies. But the repo dependency cleaner is different because it looks at the whole repo, not just the deployment package.

The repo dependency cleaner runs when you deploy to a Git repo using Gearset, and is only triggered if your deployment includes a destructive change. At the end of the deployment, Gearset checks the entire repo for a range of metadata types that can end up with missing dependencies. If any of these items have missing dependencies, Gearset deletes them - even if the items are unrelated to the deployment you just made. These deletions are then included with the deployment in the same commit to your repo.

What does the repo dependency cleaner look like in practice?

Let’s imagine that I want to deploy a destructive change to my Git repo, deleting the custom object Expenses.

When I move forward with this deployment, one of Gearset’s problem analyzers warns me about a missing dependency and suggests that I also delete the layout for the Expenses object. I’ll accept this suggestion, so I won’t be left with a missing dependency, and continue with the deployment process.

Gearset then shows me the summary of my deployment. There are two destructive changes, deleting the custom object and its layout from my Git repo.

When I run the deployment, Gearset’s repo dependency cleaner is triggered because I’m attempting to deploy a destructive change to a Git repo. The cleaner finds other items with missing dependencies in my repo, which it deletes. So, when I look at my repo in GitHub, I can see that there have been deletions from three files, not just the two files affected by my deployment package.

Digging into the line-by-line details of this commit in GitHub, I can see exactly what has been deleted: some permissions on the Admin profile. These permissions are for a managed package that I used to have in my org. I deleted the managed package itself a while back, but the permissions for it are still hanging around in my Git repo. I don’t need these permissions anymore. And more importantly, they’re undeployable without the managed package on which they depend. By deleting them for me, Gearset has cleaned up my repo to make my metadata deployable again.

When and how to disable the repo dependency cleaner

There are cases where it can be useful to disable the repo dependency cleaner, particularly if you have lots of managed packages in your orgs. Managed package metadata is often not deployed through source control, specifically where it hasn’t been or can’t be customized. But the permissions for objects and classes in a managed package can be configured as usual, so these do tend to be deployed through source control. This means that these permissions might be deployed to your repo without the metadata on which they depend. The cleaner deletes these permissions because they have missing dependencies - it cannot distinguish between permissions for managed package metadata and other permissions. In order to prevent the permissions for managed package items being deleted, the cleaner must be disabled.

To enable or disable the repo dependency cleaner, go to Account settings > Source control and use the toggle under Repo dependency cleaner. As this is a team-wide setting, it applies to every Git repo for your whole team.

It’s worth noticing that if you disable the repo dependency cleaner to avoid a deletion in your target repo, and then re-enable the cleaner afterwards, any future deployment to that repo with any destructive changes will trigger the cleaner, resulting in the deletion you wanted to avoid.

Deployments without nasty surprises

Gearset saves you from reaching your release window and only then discovering your deployments are failing for some reason. Begin a 30-day free trial of Gearset today to see how it helps you deploy successfully on the first time go with metadata comparisons, dependency analysis, problems analyzers and much more.

To get a sense of other version control best practices, alongside keeping your metadata deployable, download our free whitepaper on version control for Salesforce.