How to Map Git Branches to Salesforce Sandboxes

Mapping Git branches to Salesforce sandboxes means deciding which branch is the source of truth for each environment, so a change moves from dev to production through reviewed merges instead of org-to-org deployments. Long-lived branches map to persistent sandboxes; short-lived feature branches map to scratch orgs and developer sandboxes. Get the mapping right and promotion is just a merge. Get it wrong and you inherit merge-of-merges and silent drift.

This guide is about the mapping mechanics, not the choice of model. If you are still deciding between trunk-based, GitFlow and branch per environment, start with Git branching strategies for Salesforce teams: a decision rule, then come back here to wire it to your orgs.

Which sandbox type backs which branch?

A branch is only real if there is an org to deploy and test it in. Match each branch to the sandbox type that fits its purpose and refresh cadence:

• Feature branch to a scratch org or Developer sandbox. Disposable, created per ticket, thrown away on merge.
• Integration branch to a Developer Pro sandbox, where feature work lands and gets tested together.
• UAT branch to a Partial Copy or Full sandbox, so business users test against representative data.
• Main branch to production, always protected and only ever updated through a reviewed merge.

Refresh cadence caps how many long-lived branches you can genuinely back. Salesforce sets minimum refresh intervals of one day for Developer and Developer Pro, five days for Partial Copy and 29 days for Full, so a branch you cannot refresh is a branch you cannot trust.

How does promotion flow between branches?

Promotion is a merge, not a redeploy. A change starts on a feature branch, then moves up the chain as it clears each gate:

1. Cut a feature branch, develop against its scratch org or Developer sandbox.
2. Open a pull request into the integration branch; on merge, deploy to the integration sandbox.
3. Merge integration into the UAT branch for business sign-off in the Partial Copy or Full sandbox.
4. Merge UAT into main; the deploy to production is the same metadata that already passed UAT.

The rule that saves the most pain: never let a branch that maps to production accept a direct commit. Everything reaches it through a reviewed merge, so the branch history is also your deployment history.

How does source tracking keep a branch and its org in sync?

Source tracking records which metadata changed in a sandbox, so you pull those changes into the branch instead of guessing at a full retrieve. Deploy from git into the mapped org, and let source tracking flag anything an admin changed directly in that org. That loop keeps the branch as the source of truth and stops the org and the branch from quietly diverging.

Data, org-wide settings and licences live outside the repo, so the mapping only covers metadata. Treat those as environment configuration you seed separately, not as something a branch can promote.

What are the common mapping mistakes?

• A long-lived branch per developer sandbox. Every extra long-lived branch is another merge target that drifts. Keep feature branches short and disposable.
• Deploying org to org and calling it promotion. If the branch is not the thing you deploy, the branch history stops matching what is live.
• Backing a UAT branch with a Developer sandbox. Without representative data, sign-off tests the wrong thing and misses data-shaped bugs.
• Letting admins change production directly. A click in production that never enters git turns your mapping into fiction on the next deploy.

Make the mapping enforce itself

A mapping that lives in an onboarding doc breaks in the first busy release week. Serpent runs a ticket-based workflow with Git in the background, so the branch, its sandbox and the promotion path come from the ticket rather than from memory. More pipeline guides live in our SF Guides library.

FAQ

Do I need one branch per sandbox?

No. Map long-lived branches only to persistent environments like integration, UAT and production. Use short-lived feature branches for scratch and developer orgs.

Which sandbox should back my UAT branch?

A Partial Copy or Full sandbox, so business users test against representative data rather than an empty developer org.

How is a change promoted between environments?

Through a reviewed merge from one branch to the next, followed by a deploy from git into the mapped org. Promotion is a merge, not a re-deploy from an org.

What keeps a branch and its org from drifting apart?

Source tracking plus deploy-from-git. The branch stays the source of truth, and any direct org change surfaces as a tracked diff to reconcile.

Which branching model should I map first?

Pick the model before the mapping. See our decision rule for choosing by team size and sandbox topology.