Deploy
In Salesforce, to deploy is to move metadata and code from one org to another.
Definition
In Salesforce, to deploy is to move metadata and code from one org to another. The source is usually a sandbox, a scratch org, or a Git-backed developer environment; the target is another sandbox, a UAT environment, or production. Salesforce supports several deployment channels: Change Sets (UI-based, for related sandboxes), the Salesforce CLI (sf project deploy start), the Metadata API directly, and third-party DevOps platforms such as Copado, Gearset, Flosum, and AutoRABIT.
Each deployment moves a set of metadata components (Apex classes, Flows, custom fields, validation rules, page layouts, profiles, permission sets, and so on) into the target org. The platform validates that every component compiles, that dependencies are met, that tests pass at 75 percent coverage, and that the changes do not violate platform constraints. A successful deployment activates the new components immediately; a failed deployment rolls back the entire change set so the org is never partially deployed.
How Salesforce deployments work end to end
The deployment channels and when each fits
Change Sets are the easiest path between related sandboxes: build a set in the source, upload, deploy in the target. They are slow at scale, do not version, and do not work between unrelated orgs. The Salesforce CLI (sf project deploy) is the modern default: it works between any orgs you can authenticate against, integrates with Git, and supports validation-only runs. The Metadata API is the underlying surface for programmatic deployments. Third-party DevOps platforms wrap the Metadata API with merge management, conflict detection, and approval workflows for enterprise scale.
Validation versus deployment
Salesforce supports validation-only deployments that compile, run tests, and check dependencies without actually applying the changes. The result tells you whether the deployment would succeed, with full error details. The standard production-deploy workflow is to run a validation 24 hours before the deploy window, then deploy quickly using the same payload (a Quick Deploy is allowed within 4 days of a successful validation). This separates the slow part (compile and tests) from the risky part (actually applying changes).
The Apex test coverage requirement
Production deployments must satisfy two test rules: every Apex class deployed must have its tests pass, and overall org coverage must remain at least 75 percent. Sandbox deployments do not enforce coverage by default, which is why developers often discover coverage gaps only when promoting to production. The Salesforce CLI lets you specify which tests to run (--test-level), but production typically runs RunLocalTests or RunAllTestsInOrg for the broadest safety net.
Destructive changes and the destructiveChanges manifest
Deleting metadata uses a separate destructiveChanges.xml manifest alongside the standard package.xml. The destructive manifest lists components to delete; the platform applies destructive changes after additive changes in the same deployment. Without this dual-manifest approach, you would need a second deployment to clean up. Most real production deploys involve both additive and destructive components.
Profile and permission set deployment quirks
Profiles and permission sets do not deploy completely on their own. The Metadata API only deploys the parts of a profile or permission set that reference components included in the same deployment. Including just the profile XML does not import every grant; you have to deploy the referenced objects and fields alongside, and the platform writes only the matching grants. This is the most common deployment surprise for developers new to Salesforce.
Deployment monitoring and the Deploy Status page
Every deployment is tracked at Setup, then Deployment Status. The page shows the current job (progress percentage, components processed, errors so far) and a history of past deployments with full payloads downloadable as zip archives. Long-running deployments are common; production deploys with thousands of components and full test runs can take an hour. The page is the source of truth for what changed and when.
Source-driven development and the Salesforce DX model
Salesforce DX rethinks deployment around Git-backed source: instead of comparing sandbox to sandbox, you compare a feature branch to a target org. Scratch orgs are disposable test environments spun up from a project's source definition. The deployment unit is a Salesforce DX package (unlocked or 2GP managed), version-controlled and resolvable as dependencies. Most modern Salesforce teams have moved to this model from the older sandbox-to-sandbox Change Set workflow.
How to deploy metadata between two Salesforce orgs
The right deployment tool depends on what you are moving and where. For ad-hoc changes between related sandboxes, Change Sets are quickest. For repeatable, version-controlled deployments, use the Salesforce CLI. For production, validate first, then deploy.
- Choose the right tool
Related sandboxes and one-off changes: Change Sets. Git-backed source and CI: Salesforce CLI (sf project deploy start). Enterprise teams with multiple developers and approval gates: a third-party DevOps platform such as Copado, Gearset, Flosum, or AutoRABIT.
- Build or identify the deployment payload
For a Change Set, add components in the source org's Outbound Change Sets. For the CLI, ensure your project metadata reflects the changes; use sf project retrieve start to pull from an org or git diff against the upstream branch.
- Run a validation against production
Before deploying to production, run sf project deploy validate --target-org production --tests RunLocalTests, or use the Validate button on an inbound change set. Read the result carefully; the same code that passes in sandbox can fail in production due to data or test-class differences.
- Schedule the deployment window
Production deployments lock metadata edits while they run. Schedule outside business hours when possible. If validation succeeded within the past 4 days, you can do a Quick Deploy from the same payload, which skips re-running tests.
- Run the deployment
From the CLI, sf project deploy start --target-org production. From the Setup UI, open the inbound change set and click Deploy. Monitor progress at Setup, then Deployment Status. Errors fail the entire payload; the org is left in its pre-deployment state.
- Validate post-deploy behavior
After a successful deployment, run smoke tests on the affected flows, classes, and pages. If something looks wrong, prepare a rollback (re-deploy the previous version from Git or a saved metadata snapshot). Document the deployment in your change log.
UI-based, sandbox-to-related-sandbox only. No version control, no automation. Best for small, ad-hoc changes.
The modern default. Git-aware, scriptable, supports validation and quick deploy. Suitable for individual developers and CI pipelines.
Direct API calls for custom tooling. Used by third-party DevOps platforms under the hood.
Copado, Gearset, Flosum, AutoRABIT. Wrap the Metadata API with merge management, approval workflows, and rollback features. Best for large teams and regulated industries.
- Production deploys require Apex tests at 75 percent overall coverage and a 100 percent pass rate. A test that passes in sandbox can fail in production if it depends on data that does not exist or on a configuration difference.
- Profile XML deploys are partial: only grants for objects and fields in the same deployment are written. Including just the profile without the referenced metadata produces unexpectedly incomplete grants.
- Quick Deploy is only available within 4 days of a successful validation. After 4 days, you must validate again. Mark the validation expiry in your change log.
- Production deploys lock metadata edits during the deploy window. If anyone tries to save a Flow or class in production while a deploy runs, they get a locking error. Communicate the window.
Trust & references
Straight from the source - Salesforce's reference material on Deploy.
- deploy() Metadata API CallSalesforce Developers
- Salesforce CLI project deploy ReferenceSalesforce Developers
- Monitor DeploymentsSalesforce Help
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 does Deploy mean in Salesforce?
Q2. What are the main deployment mechanisms?
Q3. What's the modern best practice for deployments?
Discussion
Loading discussion…