SfSkills Domains Docs GitHub

Home / devops / pre-deployment-checklist

pre-deployment-checklist

Use when preparing a Salesforce metadata deployment for production and need a structured gate-check before releasing. Trigger keywords: 'pre-deploy checklist', 'what to check before deploying', 'validation deploy', 'deploy readiness', 'quick deploy window', 'checkOnly deploy', 'pre-release backup'. NOT for verifying the release after the metadata lands — use devops/post-deployment-validation. NOT for sequencing a full go-live cutover, code freeze and go/no-go gates — use devops/go-live-cutover-planning.

Open the skill folder on GitHub

Pre-Deployment Checklist

You are a Salesforce release engineer focused on the final verification gates between a completed development cycle and a production deployment. Your goal is to catch deployment blockers, confirm test coverage, validate dependency completeness, back up current production state, and confirm the deployment window is safe -- all before anyone clicks Deploy.

This skill covers the pre-deployment phase only: everything that must be true before the deployment command executes. It does not cover post-deployment smoke tests, go-live cutover sequencing, or the mechanics of specific deployment tools.

Before Starting

Gather this context before working through the checklist:

Core Concepts

Validation Deploy (checkOnly)

A validation deploy executes the full deployment pipeline -- metadata dependency resolution, Apex compilation, and test execution -- without writing any changes to the org. The Metadata API parameter is checkOnly: true; the CLI equivalent is sf project deploy validate. A successful validation produces a validatedDeployRequestId that can be redeemed for a quick deploy within 10 calendar days, skipping the test-run phase entirely. This is the single most effective tool for shrinking a production deployment window.

Key constraints: the validation must use the same test level you intend for the real deploy. If you validate with RunSpecifiedTests but the production deploy policy requires RunLocalTests, the quick-deploy ID is not usable. The 10-day window resets from the timestamp of the most recent successful validation -- not the first one.

Dependency Completeness

Every component in a deployment must have all of its transitive dependencies already present in the target org or included in the same deployment package. The MetadataComponentDependency tooling API object is the canonical way to check this programmatically. Common gaps:

The Metadata API surfaces these as deploy errors, but catching them before the deploy attempt avoids wasted validation cycles.

Pre-Release Backup

Before deploying, retrieve the current production state of every component you are about to overwrite. Use sf project retrieve start with the same package.xml used for deployment, storing the output in a timestamped backup directory. This is the fastest rollback path if the deployment introduces a regression: redeploy the backup package rather than reverting code and re-running the full pipeline.

Deployment Window Safety

Production deployments should avoid Salesforce maintenance windows (check trust.salesforce.com for your instance), batch Apex execution windows, and peak business hours. A deployment that overlaps with a scheduled maintenance can be interrupted mid-deploy, leaving partial metadata in an inconsistent state. Always confirm the instance status before starting.

Common Patterns

Pattern 1: Validate-Then-Quick-Deploy

When to use: Any production deployment where you want to minimize the deployment window and have at least 24 hours of lead time before the release.

How it works:

  1. Run sf project deploy validate --target-org production --test-level RunLocalTests against production during business hours (this is safe -- it writes nothing).
  2. Capture the validatedDeployRequestId from the output.
  3. During the scheduled release window, run sf project deploy quick --job-id <validatedDeployRequestId> --target-org production.
  4. The quick deploy skips test execution entirely, completing in minutes instead of hours.

Why not the alternative: Deploying directly with sf project deploy start runs tests during the production window, extending the outage and increasing the risk of timeout or governor limit collisions with live traffic.

Pattern 2: Staged Dependency Deploy

When to use: Large releases with 50+ components spanning multiple metadata types where transitive dependency chains are complex.

How it works:

  1. Group components into deployment waves by dependency order: schema first (objects, fields), then logic (Apex, flows), then presentation (LWC, page layouts, flexipages), then access (permission sets, profiles).
  2. Validate each wave independently against the target org.
  3. Deploy waves sequentially, confirming each wave succeeds before starting the next.

Why not the alternative: A single monolithic deployment with 200+ components is harder to debug when it fails. A single missing dependency in component 187 rolls back all 200 components. Staged deploys isolate failures to a specific wave.

Pattern 3: Backup-Before-Deploy

When to use: Every production deployment, regardless of size.

How it works:

  1. Use the same package.xml manifest that drives the deployment.
  2. Run sf project retrieve start --manifest package.xml --target-org production --output-dir backups/YYYY-MM-DD/.
  3. Commit or archive the backup directory before deploying.
  4. If rollback is needed, deploy the backup: sf project deploy start --source-dir backups/YYYY-MM-DD/ --target-org production.

Decision Guidance

SituationRecommended ApproachReason
Standard release with 24+ hours lead timeValidate-then-quick-deployMinimizes production window to minutes
Emergency hotfix with < 1 hour lead timeDirect deploy with RunSpecifiedTests targeting only affected classesFastest path; RunLocalTests may take hours in large orgs
Large release with 50+ componentsStaged dependency deploy in 3-4 wavesIsolates failures; easier rollback per wave
First deploy to a newly refreshed sandboxRun full validation first; do not assume sandbox state matches sourceSandbox refresh may have brought in production data/config that conflicts
Deploy includes destructive changesDeploy constructive changes first, then destructive in a second deployPrevents dependency breaks during the deploy window
Deploy includes Flow changesConfirm Flow version activation plan is documented separatelyFlow activation state may not carry over; manual activation may be required post-deploy

Step-by-step instructions for an AI agent or practitioner activating this skill:

  1. Inventory the release -- confirm the exact list of metadata components, the deployment tool, and the target org. Cross-reference against the source control diff or work-item list.
  2. Check dependency completeness -- query MetadataComponentDependency in the target org or review the package.xml manifest for missing transitive dependencies. Add any gaps.
  3. Back up production state -- retrieve the current production version of every component being deployed. Store in a timestamped backup directory.
  4. Run a validation deploy -- execute sf project deploy validate (or the equivalent in your tool) against the target org with the correct test level. Capture the validatedDeployRequestId.
  5. Confirm Apex test results -- verify all tests pass and aggregate code coverage meets or exceeds 75%. If using RunSpecifiedTests, confirm each test class individually meets 75%.
  6. Check the deployment window -- confirm trust.salesforce.com shows no maintenance for your instance, no batch jobs are scheduled during the window, and the release is scheduled off-peak.
  7. Go / No-Go decision -- walk the Review Checklist below. If any item is unchecked, do not deploy.

Review Checklist

Run through these before any production deployment:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. RunSpecifiedTests has stricter per-class coverage -- Unlike RunLocalTests which requires 75% aggregate coverage across the entire org, RunSpecifiedTests requires 75% coverage per class included in the deployment package. A class with 60% coverage passes under RunLocalTests (if the org average is above 75%) but fails under RunSpecifiedTests.
  2. Quick-deploy ID expires silently -- The 10-day window from a validation deploy is a hard cutoff. There is no warning at day 9. If you attempt a quick deploy on day 11, the API returns an error and you must re-validate from scratch. Track the validation timestamp explicitly.
  3. Validation deploy can lock components -- While a validation deploy does not write metadata, it does acquire compile locks on Apex classes during test execution. Running a validation deploy while another deploy or validation is in progress can cause lock contention errors. Check the Deployment Status page for in-flight deployments before starting a validation.
  4. Sandbox test results do not predict production -- Apex tests that pass in a partial-copy sandbox may fail in production due to data volume differences, org-wide defaults, sharing rules, or installed managed packages. Always validate directly against production (using checkOnly: true), not just against a staging sandbox.
  5. Destructive changes in the same package can break dependencies -- If your package.xml includes both a new field and a destructiveChangesPost.xml that deletes an old field referenced by a validation rule, the deploy may fail even though the destructive change is marked as "post." Process constructive and destructive changes in separate deploy operations when dependencies exist between them.

Output Artifacts

ArtifactDescription
Pre-deployment checklistCompleted go/no-go checklist with all gates verified
Validation deploy resultsTest pass/fail summary, coverage report, and validatedDeployRequestId
Pre-release backupRetrieved production metadata stored in timestamped backup directory
Dependency gap reportList of missing transitive dependencies found during pre-deploy analysis

Package files