Source-Driven Development
Source-driven development is a Salesforce development approach where the version control system, not the org, holds the authoritative copy of your metadata.
Definition
Source-driven development is a Salesforce development approach where the version control system, not the org, holds the authoritative copy of your metadata. Your Apex, Lightning Web Components, objects, and configuration live as files in a Git repository, and orgs are treated as environments you build from that source.
This model is the foundation of Salesforce DX. Developers retrieve metadata in source format, work locally, and push or deploy those files into scratch orgs or sandboxes for testing. Because the repository is the single source of truth, teams get history, code review, branching, and continuous integration on Salesforce work the same way other software teams have had them for years.
How source-driven development reshapes a Salesforce team
Moving the source of truth off the org
For most of Salesforce history, the production org was the real source of truth. Even teams that exported metadata into version control still treated the org as authoritative, and the repository was a backup at best. Change sets reinforced this, moving components from one org to another with the live org as the reference point. Source-driven development inverts that relationship. The Git repository becomes authoritative, and orgs become things you build from source. Salesforce describes this directly in the package development model, where the source of truth is your version control system rather than any single org. That one change has large effects. You can branch, review, and merge metadata like any other code. You can roll back a bad change by reverting a commit. You can stand up a clean environment from the repository whenever you need one. The org stops being a fragile, hand-edited artifact that nobody dares rebuild, and becomes a disposable target you can recreate on demand from files you trust.
Scratch orgs as disposable environments
Scratch orgs are the environment type built for this model. A scratch org is a short-lived, source-driven org that you spin up from your project configuration and metadata, use for a few days, then throw away. Salesforce positions them as disposable, so you create a fresh one per feature or task instead of sharing one long-lived sandbox that slowly drifts out of sync. The workflow is push and pull. After an initial deploy, you push local changes into the scratch org to test them, and pull (retrieve) any changes you made through the org UI back into your project files. Source tracking watches the difference between your local project and the org, so the CLI can tell you exactly what changed on each side. Because a scratch org always starts from the repository, every developer works from the same baseline. There is no question of which sandbox has the latest version, and a corrupted environment is fixed by deleting it and creating another one rather than by debugging accumulated state.
Source tracking is what makes it practical
Source tracking is the feature that keeps a local project and an org in agreement. It records changes as you create, update, or delete metadata, on both the local file system and the org, so tooling can show you a precise diff before you push or pull. Without it, you would be guessing which of dozens of components actually changed. Tracking is available on scratch orgs and on Developer and Developer Pro sandboxes. It is not available on partial copy sandboxes, full copy sandboxes, or production orgs, which matters when you plan your pipeline. Source-tracked environments are where active development happens, and the non-tracked environments downstream receive deployments instead of being edited by hand. This split is why source-driven teams keep change authoring on scratch orgs or Developer sandboxes, then promote the resulting source through staging and production with the repository driving every step. Knowing which org types track changes saves a lot of confusion when a deploy to a full sandbox does not behave the way a push to a scratch org did.
Org development model versus package development model
Salesforce DX supports two ways of organizing source-driven work, and they suit different teams. The org development model works with orgs that do not have source tracking, such as non-source-tracked sandboxes, Developer Edition orgs, Trailhead Playgrounds, or a production org. You retrieve and deploy metadata directly, while still storing everything in a source control repository. It is a gentle on-ramp for teams moving off change sets that are not ready to adopt scratch orgs yet. The package development model is the fuller expression of the idea. You organize source into packages built around a set of features you want to deliver together, develop against source-tracked scratch orgs, and lean on continuous integration and deployment. In this model the version control system is unambiguously the source of truth. Smaller, modular source files also mean fewer merge conflicts when several developers work at once. Many teams start with the org development model and grow into package development as their automation and discipline mature.
The Salesforce CLI and project structure
Source-driven development runs on the Salesforce CLI and a defined project layout. A DX project is a directory of metadata in source format, governed by a configuration file named sfdx-project.json. That file declares your package directories, the login URL, and the source API version, and tools read it to know how your project is shaped. Source format matters here. The CLI retrieves metadata decomposed into smaller files rather than the large bundled XML the older Metadata API returned. A custom object, for example, is split so that each field and list view can live in its own file. Smaller files produce cleaner diffs and far fewer merge conflicts, which is exactly what version control wants. The CLI then handles the verbs of the model: create a scratch org, push and pull source, run Apex tests, and deploy or retrieve against any org. Because it is a command line tool, every one of those actions scripts cleanly into a CI job, which is how source-driven development connects local work to an automated pipeline.
Continuous integration and collaboration payoff
The reason to adopt this model is what it makes possible for a team. With metadata in Git and a CLI that scripts every step, you can wire a pipeline that, on each pull request, spins up a fresh scratch org, deploys the branch, runs the Apex test suite, and reports back before anyone merges. Problems surface in review instead of in production. Collaboration improves for the same structural reasons. Source control gives you visibility and audit history into every change, plus a real way to undo changes that caused harm. Multiple developers can work in parallel without stepping on each other, because each has an isolated scratch org and the modular source format reduces conflicts when branches merge. DevOps Center builds on this foundation for admins and lower-code teams, using a source control repository in DX project structure as the single source of truth across the pipeline. The result is that admins, developers, release managers, and QA all read from and write to the same authoritative source, which is the whole point of working this way.
Set up a source-driven project
Source-driven development is a way of working, not a single button. You set it up by creating a DX project, connecting it to version control, and enabling source-tracked environments. These steps describe the standard path using the Salesforce CLI.
- Create a DX project
Use the Salesforce CLI to generate a new project. This produces the standard directory layout and an sfdx-project.json file that declares your package directories and source API version. Commit this skeleton to Git as your starting point.
- Authorize a Dev Hub
Source-driven development uses scratch orgs, which are created from a Dev Hub. Enable Dev Hub in a production or Developer Edition org, then authorize it from the CLI so your project can request scratch orgs.
- Create a scratch org and push source
Spin up a scratch org from your project, then push your local source into it. Source tracking now records changes on both sides, so you can push local edits in and pull org edits back to keep the project and org in sync.
- Wire continuous integration
Add a CI job that, on each branch or pull request, creates a scratch org, deploys the source, and runs your Apex tests. Because the CLI scripts cleanly, this turns the repository into the gate that every change passes through.
Best for teams moving off change sets. Works with non-source-tracked sandboxes, Developer Edition orgs, or production, storing everything in source control while you retrieve and deploy directly.
Organizes source into packages and develops against source-tracked scratch orgs with CI/CD. Here the version control system is unambiguously the source of truth.
Available on scratch orgs and Developer or Developer Pro sandboxes. Not available on partial copy, full copy, or production orgs, which receive deployments instead.
- Change sets treat the production org as the source of truth. Source-driven development moves that authority to the repository, so retrain the team to commit changes rather than build directly in an org.
- Source tracking does not work on partial copy, full copy, or production orgs. Plan to author changes on scratch orgs or Developer sandboxes and deploy downstream.
- Scratch orgs are temporary and expire. Never store anything you cannot recreate from source, because the org is meant to be thrown away.
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Source-Driven Development.
- Track Changes Between Your Project and OrgSalesforce
- Manage Source Tracking for Your OrgSalesforce
Hands-on resources to go deeper on Source-Driven Development.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is Source-Driven Development?
Q2. What does it enable?
Q3. What are orgs in this model?
Discussion
Loading discussion…