Delta Deployments in Salesforce: How to Deploy Only What Changed

A delta deployment sends only the metadata that changed between two Git references, instead of the whole project. You compute it by diffing commits, generating a package.xml from the diff, and deploying that manifest. It is faster and less risky than a full deployment in one specific way, and more fragile in another: a partial package can fail on dependencies a full package would have satisfied by accident.

What is a delta deployment in Salesforce?

A delta deployment is a metadata deployment whose manifest is derived from a Git diff rather than from your whole source tree. Three moving parts:

• The diff. Two Git refs, usually your feature branch and the branch you are merging into.
• The manifest. A package.xml listing only added and modified components, plus a destructiveChanges.xml listing deletions and renames.
• The deployment. A normal metadata deploy against that manifest.

Nothing about it belongs to a DevOps vendor. Every tool offering delta deploys, Serpent included, runs a version of the same three steps.

How do you compute a delta package?

The common open-source route is sfdx-git-delta, the plugin the Salesforce Developers blog walked through for unpackaged sources. Note that it is an unofficial, community-maintained plugin, so treat it as a dependency you own.

1. Make sure your CI checkout has enough Git history. A shallow clone with a depth of one cannot diff against a base branch, and this is the single most common reason a delta job produces an empty or wrong package.
2. Generate the manifest: sf sgd source delta --from origin/main --to HEAD --output-dir .
3. Add --generate-delta if you want the changed source files copied out alongside the manifest. Use it only when --to is HEAD.
4. Guard against an empty manifest. A deployment with an empty package.xml fails, so your pipeline should skip the deploy step rather than error out.
5. Deploy, applying deletions after the additions: sf project deploy start -x package/package.xml --post-destructive-changes destructiveChanges/destructiveChanges.xml
6. Validate first: run the manifest as a check-only deploy before the real one.

Which dependency traps make delta deployments fail?

This is the part tutorials skip. A full deployment carries every component, so implicit dependencies resolve silently. A delta carries a subset, and every previously invisible dependency becomes an error.

Profiles and permission sets

Add a field in the delta and its access lives in the profile, which is a separate file. If the profile file did not change, it is not in the delta, and the field lands in the target with nobody able to see it. The retrieve side compounds this: Salesforce only returns security settings for metadata types referenced in the retrieve request, with user permissions, IP ranges and login hours always included. Treat profiles as something you deploy deliberately, not something the diff decides for you.

Picklists, record types and translations

Removing a picklist value touches record types and translations that reference it. sfdx-hardis added delta with dependencies precisely for this case, because the failure often does not appear in the delta deployment at all. It appears in the next full deployment, weeks later, in a different pipeline.

Apex tests

If you deploy a changed class under RunSpecifiedTests, its test class has to be in the target and named in the test list. A delta that includes the class but not the test is a coverage failure waiting for production.

Flows

Flow deletion through destructiveChanges.xml is a documented platform gap. The workaround is to deactivate first by deploying a FlowDefinition with activeVersionNumber set to zero.

Metadata that lives inside one file

Custom labels, workflows and matching rules pack many members into a single file. A one-line change to one member marks the whole file changed, and force-including these needs full Git history, not a shallow clone.

Renames

Git sees a rename as a delete plus an add. Deploy them in the wrong order and you either delete a component that is still referenced or create a duplicate. Post-destructive ordering exists for this reason.

When should you deploy full instead of delta?

A useful default, and the one sfdx-hardis ships with, is delta for feature branches merging into a shared branch, and full deployments between shared environments. The reasoning is that the further up the pipeline you go, the more likely the target has drifted from source control, and a delta assumes source control is the truth.

Go full when any of these is true:

• The target org has had manual changes since the last deploy.
• The change touches profiles, permission sets or sharing settings broadly.
• You are promoting between two long-lived environments rather than merging a feature.
• You are recovering from a failed or partially applied deployment.

Keep a manual override. sfdx-hardis uses a NO_DELTA marker in the commit title, which is a good pattern to copy whatever tooling you use: the person who knows the change is risky should be able to force a full deploy without editing pipeline config.

What does a safe delta pipeline look like?

1. Full clone, or at least enough depth to reach the merge base.
2. Generate the manifest, then print it into the build log so a human can read what is about to ship.
3. Skip cleanly when the manifest is empty.
4. Check-only deploy, then real deploy, with destructive changes applied last.
5. Full deployment on a schedule, weekly or per release, to catch the drift the deltas never touched.

That last step is the one teams drop, and it is the one that catches the picklist-and-translation class of failure before a release is on the line. More Salesforce delivery playbooks live in our SF Guides library.

FAQ

Are delta deployments safer than full deployments?

They are faster and touch less, which lowers blast radius. They are not inherently safer, because a partial package can miss a dependency that a full package would have carried.

Do I need sfdx-git-delta to do delta deployments?

No. It is the most common open-source route, and it is unofficial and community-maintained. Most commercial Salesforce DevOps platforms compute the delta for you.

Why is my delta package empty in CI but not locally?

Almost always a shallow clone. Your CI checkout needs enough Git history to reach the commit you are diffing from.

How do I delete metadata in a delta deployment?

Through destructiveChanges.xml, applied after the additive package. Flows are the exception: deactivate them with a FlowDefinition change first.

Should profiles be part of the delta?

Deploy them deliberately rather than letting the diff decide. Profile files only carry settings for the metadata types included in the retrieve, so a diff-driven profile is rarely the profile you meant.