A practical handbook for Salesforce architects, developers, and DevOps engineers who own how code gets from a developer's editor to a user's production org. Written by people who have shipped Salesforce code at scale and have the scars to prove it.
The aim of this guide is concrete: cut the time you spend reinventing release runbooks, pick the right packaging strategy on day one, and avoid the deploy disasters that everybody keeps running into because the docs are scattered across a dozen different Salesforce guides.
- Salesforce DevOps engineers designing pipelines for one team or one hundred.
- Architects deciding between org-based deploys, 2GP unlocked packages, and 2GP managed packages.
- Tech leads setting up a new Salesforce project and choosing the conventions that will hold up two years from now.
- Developers who keep getting bitten by source tracking, mixed metadata, and "worked in QA, broke in production".
It assumes you know what an Apex class is, what a sandbox is, and what sfdx-project.json is for. It does not assume you know the difference between deploy --check, deploy validate, deploy quick, and push. By Chapter 18, you will.
Pick the chapter that matches what you are doing right now.
| Chapter | Read it when |
|---|---|
| 00. Quickstart | You want a working scratch org and a green deploy in 15 minutes. |
| 01. Mental Model | You are starting on Salesforce DevOps and want the four-stores-of-truth picture in your head. |
| 02. Project Structure | You are setting up sfdx-project.json, package directories, source layout. |
| 03. Source Format and Metadata Format | You see folders called force-app/ versus manifest/ and want to know what each one means. |
| Chapter | Read it when |
|---|---|
| 04. Branching Strategies | You are picking a Git workflow for your Salesforce repo. |
| 05. .forceignore and Manifests | Your deploys keep including files you don't want, or excluding files you do. |
| Chapter | Read it when |
|---|---|
| 06. Scratch Orgs From Zero | You have never used a scratch org and need the foundational picture. |
| 07. Scratch Org Definitions | You are setting up the JSON config that controls what scratch orgs you get. |
| 08. Org Shapes | Your scratch orgs need to look like production. |
| 09. Source Tracking | You are confused about why push does one thing in scratch orgs and not in sandboxes. |
| 10. Scratch Org Snapshots | Scratch creation is too slow. |
| 11. Scratch Orgs in CI | You are wiring scratch orgs into a CI pipeline. |
| 12. Troubleshooting Scratch Orgs | Something is wrong and you need a structured triage. |
| Chapter | Read it when |
|---|---|
| 13. Packaging Overview | You need to pick between org-based deploys and packages. |
| 14. 2GP Unlocked Packages | You have decided on unlocked packages and need to actually build one. |
| 15. 2GP Managed Packages | You are publishing to the AppExchange or building an ISV product. |
| 16. Dependencies and Ancestry | Your packages reference other packages, and you need to understand the lock-in. |
| 17. Versioning Strategy | You need to decide what your version numbers mean. |
| Chapter | Read it when |
|---|---|
| 18. Deploy Semantics | You are mixing up deploy, push, validate, and quick deploy. |
| 19. Test Levels | You want to know when to use RunLocalTests versus RunSpecifiedTests. |
| 20. Destructive Changes | You need to delete metadata in a target org. |
| Chapter | Read it when |
|---|---|
| 21. CI/CD Architecture | You are designing a pipeline for a Salesforce project. |
| 22. Secrets and Auth | You are wiring up CI to authenticate to Salesforce. |
| 23. Sandbox Strategy | You are deciding which sandbox types you need and how often to refresh. |
| 24. Rollback and Hotfixes | A release went wrong and you need a way back. |
| 25. AI-Assisted Development | Your team uses Claude Code, Copilot, Codex, or Cursor with Salesforce. |
| Chapter | Read it when |
|---|---|
| 26. Troubleshooting | Something deployed fine yesterday and breaks today. |
| 27. Anti-Patterns | You want to know what to avoid before you do it. |
| 28. Glossary | You see a term and want one paragraph of context. |
| Folder | What's in it |
|---|---|
| Cookbook | End-to-end worked examples. |
| Templates | Copy-paste skeletons for sfdx-project.json, scratch org definitions, CI configs, package manifests. |
| Case Studies | Anonymised real incidents and how they were resolved. |
If you only have time for three rules:
-
Build the package version once. It travels through QA, UAT, and production unchanged. If your pipeline rebuilds at each stage, you are testing one artifact and shipping a different one.
-
Validate before you deploy to production.
sf project deploy validateruns all the tests and saves the result for 4 days.sf project deploy quickthen promotes that validated job in seconds. A 90-minute production deploy becomes a 5-minute quick deploy. -
Source is the truth. What is in the org but not in source control will be lost. Adopt a retrieve-after-UI-change discipline. Treat the Setup UI as a place to author, not a place to store.
Every DevOps decision in Salesforce is about which of these the answer lives in. Get clear on which is canonical for what, and most of the rest of the discipline falls out of it.
This guide is at version 0.1.0. See CHANGELOG.md for what's in this release.
Every chapter ends with a ## References section linking to the canonical Salesforce documentation. The full source index is in REFERENCES.md. Verification status and last-checked date are in VERIFICATION.md.
Contributions are welcome. See CONTRIBUTING.md for the conventions and process. Be kind: see CODE_OF_CONDUCT.md.
The text and diagrams are released under Creative Commons Attribution 4.0. Use this in your own work, including commercial work. Credit the source.
The chapters here are direct. Sentences are short. There is no marketing language and no padding. When something is hard, the guide says it is hard. When a Salesforce feature has rough edges, the guide names them.
If you find an error or something out of date, fix it where you find it. The point of this guide is to keep the next person from losing a day to the same problem.