Source-driven development in Salesforce, explained

Definition first: source-driven development is the model where your Git repository, not any org, is the source of truth for your Salesforce configuration and code. Orgs become disposable environments you deploy from the repo, rather than places you copy changes between. Everything else in this guide follows from that one sentence.

What is source-driven development in Salesforce?

In source-driven development, every change lands in version control first and reaches an org second. The repository holds the intended state of the org. A deployment is the act of making an org match that intent.

Three practical properties come with it:

• History. Every change has an author, a timestamp and a reason attached to it.
• Reversibility. Rolling back is deploying a previous known-good state, not reconstructing one from memory.
• Parallelism. Two people can work on the same object without one silently overwriting the other, because the merge is explicit.

How is it different from org-to-org deployment?

Org-to-org deployment, whether by change sets or by direct comparison of two orgs, treats a live org as the reference. That is the actual distinction, and it has consequences.

• Where truth lives. Org-to-org: the source org. Source-driven: the branch.
• What a release is. Org-to-org: a list of components assembled by a person. Source-driven: a diff between two commits.
• What history you get. Org-to-org: whatever the deployment log kept. Source-driven: the full change history, forever.
• How you roll back. Org-to-org: rebuild the previous state manually. Source-driven: deploy the previous commit.
• Who can audit it. Org-to-org: whoever has admin access. Source-driven: anyone who can read the repo, including auditors who should never touch production.

Note what is not on that list: speed. Source-driven development is not automatically faster. It is repeatable, which is a different and more durable property.

What is source tracking, and where does it work?

Source tracking is the platform feature that records which components changed in an org or in your local project since the last sync, so you can pull only what actually moved instead of retrieving everything and reading a diff.

The constraint people hit is coverage. Source tracking is available in scratch orgs and in Developer and Developer Pro sandboxes. It is not available everywhere, which means a source-driven model has to answer for the environments that cannot track changes for you: full sandboxes, partial copies and production. Those are exactly the orgs where undocumented changes happen.

Source format or metadata format: which do you commit?

Commit source format. The two formats describe the same metadata differently:

• Metadata format is the Metadata API shape: broad files per object plus a package.xml manifest. One field edit rewrites a large file, so the diff carries the whole object and reviews get noisy.
• Source format decomposes that structure: each field, validation rule and list view gets its own file in a folder tree, with package directories declared in sfdx-project.json.

The practical effect is on review and merge, not on function. Small files produce readable diffs and far fewer conflicts when two people touch the same object, which is precisely the situation source-driven development exists to survive.

What happens when the org and the repo disagree?

This is the question most explainers skip, and it is the one that decides whether the model survives contact with a real Salesforce team. Someone will always change something in production. A hotfix at midnight, an admin adding a picklist value, a managed package upgrade rewriting metadata you had committed.

Decide these three things before you migrate, not after:

1. Who wins. The repo wins by policy. That means an out-of-band change is not "lost", it is reconciled: retrieved, committed with an explanation and then re-deployed from the branch.
2. How you find out. Run drift detection against production on a schedule. Discovering divergence at release time is discovering it too late.
3. What is deliberately out of scope. Some metadata is genuinely environment-specific or owned by an installed package. Write that exclusion list down. An honest exclusion list beats a repo everyone quietly distrusts.

How do you adopt this without a Git-fluent team?

Most Salesforce teams are admins and consultants, not CLI users, and this is where source-driven migrations usually stall. Sequence it so that nobody has to learn Git to keep working:

1. Pick one package boundary to start. One team, one set of metadata. Do not try to commit the whole org in week one.
2. Retrieve into source format and get a clean deploy of that scope into a sandbox before anyone changes their habits.
3. Put a gate in front of production. Even a manual approval on a branch counts. Truth without a gate drifts back within a month.
4. Keep the everyday interface familiar. Admins should still work in a ticket or a work item; the commit, branch and merge should happen underneath them.
5. Add drift detection last. Once the pipeline is trusted, it tells you where the model is leaking.

FAQ

Does source-driven development require every admin to learn Git?

No. It requires the repository to be authoritative. Which humans interact with Git directly is a tooling choice, not a property of the model.

Do I have to convert my org to source format all at once?

No. Convert by package boundary or by team. A partial repository that is genuinely authoritative for its scope beats a complete one nobody trusts.

Is source-driven development the same as CI/CD?

No. Source-driven development decides where truth lives. CI/CD automates moving that truth into orgs. You can have the first without the second, but not usefully the reverse.

What about metadata that cannot be source controlled?

Some settings and package-owned components will not round-trip cleanly. Document them as excluded and control them by procedure instead of pretending the repo covers them.

Serpent is built for exactly the team this guide describes: the repository stays the source of truth while admins and consultants work in tickets, with delta deployments, drift detection and one-click rollback on top. More reference guides are in SF Guides.