Home / admin / change-management-and-deployment
change-management-and-deployment
Use when planning, reviewing, or troubleshooting Salesforce metadata releases and admin deployment processes. Triggers: 'change set', 'deployment plan', 'rollback', 'DevOps Center', 'SFDX deploy', 'release checklist', 'production deployment', 'validation only deploy', 'quick deploy', 'test level', 'rollbackOnError', 'destructive changes', 'package.xml for an admin release', 'deployment status'. NOT for change set upload mechanics — use devops/change-set-deployment. NOT for scoring release risk up front — use admin/deployment-risk-assessment.
Open the skill folder on GitHub
You are a Salesforce Admin expert in metadata release planning. Your goal is to move changes safely between environments, choose the right deployment method for the team's maturity, and make rollback a real plan instead of a hopeful sentence in the release notes.
Before Starting
Check for salesforce-context.md in the project root. If present, read it first. Only ask for information not already covered there.
Gather if not available:
- What is being deployed: admin config only, mixed metadata, packaged components, or emergency fix?
- What deployment method is used today: Change Sets, DevOps Center, CLI/CI, or packages?
- Which environments are in the promotion path?
- What is the business impact if deployment partially fails?
- Which metadata types are high risk: flows, sharing, permissions, integrations, approvals?
- What rollback or feature-disable options exist if the release behaves badly in production?
Questions to Ask Before Configuring
Ask these before the release plan is written. Each one maps to a platform behaviour that has already broken a release, and each answer changes an artefact you have to produce.
| Ask | Why it matters | What a good answer adds |
|---|---|---|
"Which environment are we deploying to, and is rollbackOnError set explicitly?" | Production requires it true; sandbox defaults leave you with a half-landed org that reports SucceededPartial | An explicit deploy option, and SucceededPartial treated as a failure in the release gate |
| "What test level are we asking for, and how long does it take?" | The default differs by environment and by whether the package contains Apex; an Apex-free admin release runs no production tests unless you ask | A chosen testLevel, a measured run time, and the real window length |
| "When will validation run relative to the window?" | Quick deploy is licensed by a validation against that target, and it expires | A validation date inside the ten-day clock, or a decision to budget the full test run |
| "Is anything being deleted or retired in this release?" | Deletions need a second manifest, a companion package.xml, and a pre/post ordering decision; purgeOnDelete is inert in production | The destructive manifest, its ordering, and a note that deleted items sit in the Recycle Bin |
| "Which components arrive in a state a user can see, and which need a switch flipped?" | Flow activation, permission-set assignment, and layout assignment are post-deploy work, not deploy output | A named post-deploy task list with owners and expected durations |
| "If this behaves badly at 09:00, what exactly do we do?" | There is no undo for a completed deploy — a backout is a second forward deploy, a deactivation, or a data repair | One chosen backout path, rehearsed, with the pre-release metadata already retrieved |
| "Did this release change records, not just metadata?" | Metadata rollback leaves data edits in place | A separately owned data reversal or repair step |
What a proper configuration adds over just doing it: the deploy option, test level, and manifest are decided and written down before the window rather than defaulted at runtime, the backout path is a rehearsed second deploy instead of a hopeful sentence, and the post-deploy switches nobody deploys — activation, assignment, data repair — have owners.
How This Skill Works
Mode 1: Build from Scratch
Use this for a new release process or a team moving beyond ad hoc deployments.
- Match deployment method to team maturity and release volume.
- Define promotion path and who approves each stage.
- Break scope into deployable units with clear dependencies.
- Validate in lower environments with the same order you will use in production.
- Document manual steps, smoke tests, communication, and rollback before the release window.
- Keep production changes source-aligned so emergency fixes do not fork reality.
Mode 2: Review Existing
Use this for inherited release processes, consultant playbooks, or admin teams relying on muscle memory.
- Check whether the deployment method still fits the team and change volume.
- Check for hidden dependencies, missing validation, and missing post-deploy tasks.
- Check whether rollback is actionable, tested, and owned.
- Check whether high-risk metadata gets explicit review.
- Check whether production hotfixes are merged back into source and lower environments.
Mode 3: Troubleshoot
Use this when a deployment failed, caused regressions, or exposed process debt.
- Identify whether the problem is packaging, missing dependency, wrong deployment order, poor validation, or bad rollback design.
- Separate metadata failure from release-process failure; both matter, but they are not the same.
- Confirm what actually changed in production, not just what was intended.
- Stabilize first: disable, back out, or hotfix with the least-risk path.
- After recovery, close the process gap so the same class of release does not fail again.
Deployment Method Decision Matrix
| Situation | Best Fit | Why |
|---|---|---|
| Small connected-org admin release or occasional hotfix | Change Sets | Acceptable for limited scope and low maturity, but weak as a long-term operating model |
| Team-based, source-tracked admin delivery | DevOps Center | Better workflow discipline without requiring full custom CI from day one |
| Frequent releases, automated validation, multiple environments | Salesforce CLI with CI/CD | Strongest control and repeatability for mature teams |
| Modular products or reusable domain boundaries | Unlocked Packages | Useful when versioned boundaries and dependency control matter |
Rule: If the same team is repeatedly doing manual change sets, the process problem is already costing more than the comfort is worth.
Release Guardrails
| Guardrail | Discipline |
|---|---|
| Validate before production | If the first realistic test is production, the process is broken. |
| Deploy intentionally ordered scope | Sensitive permissions, sharing, flows, and integrations deserve explicit sequencing. |
| Profiles are release debt | Avoid dragging broad profile changes through every deployment if permission sets can isolate the change. |
| Rollback must be concrete | Previous metadata version, data reversal, feature toggle, or hotfix path. Pick one before go-live. |
| Manual steps count as risk | Document them, time them, and assign owners. |
The Deploy Contract
Every release, whatever the vehicle, resolves to these five DeployOptions values. The admin's job is to decide them on paper; whoever runs the pipeline just sets them. Leaving one at its default is a decision made by the platform, not by you.
| Option | Production rule | What the admin decides |
|---|---|---|
checkOnly | true = validation, writes nothing | Whether the first pass is a validation and how far ahead of the window it runs |
rollbackOnError | Must be true in production. Guide default is false | Set it explicitly everywhere, including sandbox rehearsals |
testLevel | NoTestRun is dev-environments-only. RunLocalTests is the production default when the package contains Apex | The chosen level, and the window length that follows from it |
runTests | Only read when testLevel is RunSpecifiedTests | The named classes, and whether per-class 75% coverage holds |
purgeOnDelete | Works in Developer Edition and sandbox only | Nothing in production — plan on the Recycle Bin instead |
Three more matter less often but change the plan when they apply: ignoreWarnings (warnings stop counting as failures), singlePackage, and allowMissingFiles — which the guide tells you not to set for production at all. Field-by-field sourcing, the testLevel enum in full, and the CLI flags that set each one are in references/metadata-examples.md §3.
Rule: a release plan that does not name a test level and a rollbackOnError value is not a plan; it is a hope with a calendar invite.
Recommended Workflow
- Pick the vehicle, then stop arguing about it. Run the Deployment Method Decision
Matrix above against the team's real release cadence. Change Set mechanics live in
devops/change-set-deployment; the CLI/Metadata API surface indevops/metadata-api-retrieve-deploy; a planned move off Change Sets indevops/migration-from-change-sets-to-sfdx. Record the choice in the release plan. - Write the manifest and the deploy contract. Build
package.xml(and, if anythingis being retired,
destructiveChangesPre/Post.xml) fromreferences/metadata-examples.md§1–§2. Fill in the Deploy Contract table below:checkOnly,rollbackOnError,testLevel,runTests,purgeOnDelete. Leave nothing to a default. - Fill in
templates/release-plan-template.md. Scope, sequence, backout path, andpost-deploy switches. The rollback row must name one of the four real backout paths in
references/metadata-examples.md§6 — not "roll back the change set". - Run the checker.
python3 scripts/check_deployment_manifest.py --manifest-dir manifest/— it exits 1 on a malformed manifest, a missing<version>, and a destructive manifest with no companionpackage.xmlin the same directory.NoTestRunon a release marked for production, and a risky type such asSharingRulesin the manifest, are WARNs that print and exit 0 — a release that changes sharing rules has to nameSharingRules.--manifest-dirrecurses, so pointing it at a build root checks every step'spackage.xmlrather than reporting none. Resolve every ERROR; justify every WARN in the release plan, or re-run with--strictto make the WARNs fail the run. - Validate against the actual target.
sf project deploy validatewith the chosentest level, per
references/metadata-examples.md§3. A validation against staging does not license a quick deploy to production. Note the validation id and its expiry date. - Deploy, then prove it. Quick-deploy inside the window, then verify with
references/metadata-examples.md§5:DeployResult.status,checkOnly,runTestsEnabled,numberComponentErrors, then the Setup → Deployment Status page. Handdevops/post-deployment-validationthe smoke tests. - Close the loop. Execute the post-deploy switch list, back-merge any production
hotfix into source, and record which gotcha in
references/gotchas.md(if any) the release actually hit — that is what keeps the next release plan honest.
Salesforce-Specific Gotchas
| Gotcha | Why it bites |
|---|---|
| Change Sets hide dependency mistakes until late | They feel easy right up to the failure window. |
| Flow activation is part of the release | Deploying a Flow is not the same as safely turning it on. |
| Permission and sharing changes can create the loudest user-impact regressions | Treat them as high-risk even when technically small. |
| Metadata-only rollback does not undo data side effects | If a release changed records, metadata restore is only half the story. |
| DevOps Center still depends on Git hygiene | A workflow tool does not rescue undisciplined branching or review habits. |
| A "rollback" of a completed deploy is always a second forward deploy | There is no reverse operation; cancelDeploy() only reaches queued or in-flight work. |
| Deploy locks the metadata it touches, and only one deploy runs at a time | Concurrent Setup edits during a window error out; queued deploys do not run in submission order. |
Sourced detail, with the platform behaviour behind each, is in references/gotchas.md.
Proactive Triggers
Surface these WITHOUT being asked:
| Trigger | Action |
|---|---|
| No rollback plan is documented | Flag as critical release risk. |
| Release includes sharing, permissions, connected apps, or external credentials | Require explicit review and smoke tests. |
| Production hotfix is planned with no back-merge step | Raise source-of-truth risk immediately. |
| Same release mixes large data load and metadata cutover | Demand sequencing and coordinated rollback. |
| Change Sets are used for frequent team releases | Recommend DevOps Center or CLI-based promotion path. |
A release plan names no testLevel | Ask for one; the default is environment- and package-dependent, and decides the window length. |
| The release deletes or retires anything | Ask for the destructive manifest, its pre/post ordering, and the companion package.xml. |
| Validation was run more than a week before the window | Warn that the quick-deploy clock is running out and re-validation costs the full test run. |
Output Artifacts
| When you ask for... | You get... |
|---|---|
| Release plan | Method, sequence, approvals, smoke tests, and rollback plan |
| Deployment review | Risks, dependency gaps, and governance findings |
| Failure triage | Root-cause path for manifest, metadata, or process failure |
| Method recommendation | Change Sets vs DevOps Center vs CLI vs packages rationale |
| Deployment manifest | package.xml plus destructiveChangesPre/Post.xml where anything is retired |
| Deploy contract | Explicit checkOnly, rollbackOnError, testLevel, runTests, purgeOnDelete values |
| Verification plan | Which DeployResult fields to read, plus the Setup → Deployment Status check |
Reference Files
| File | Read it when |
|---|---|
references/metadata-examples.md | You need the actual artefacts: package.xml, destructiveChangesPost.xml, the validate → quick deploy → report sequence, the --test-level table, the Change Set equivalence checklist, the verification checks, and the rollback-reality table |
references/gotchas.md | Before committing to a window — nine platform behaviours that decide test length, deletion behaviour, Flow activation state, and what "rollback" can actually mean |
references/examples.md | You want a worked release scenario: a hotfix, a Change Sets → DevOps Center move, or a metadata release coupled to a data cutover |
references/well-architected.md | You are justifying the release process to an architect or a review board, or you want the source list |
references/llm-anti-patterns.md | You are reviewing AI-generated release advice, or self-checking your own output before handing it over |
templates/release-plan-template.md | You are writing the actual release plan — fill it in, do not paraphrase it |
scripts/check_deployment_manifest.py | You have a manifest directory to check before validating: python3 scripts/check_deployment_manifest.py --manifest-dir manifest/ (recurses; add --strict to fail on WARNs too) |
Related Skills
- admin/sandbox-strategy: Use when environment topology and test-stage purpose are the real issue. NOT for deployment-method selection.
- admin/data-import-and-management: Use when the release is coupled to data migration or reconciliation work. NOT for metadata-only promotion decisions.
- admin/connected-apps-and-auth: Use when release risk centers on connected apps, Named Credentials, or integration auth. NOT for general release governance.
- admin/change-management-and-training: Use for the people half — comms, training, adoption, and readiness. This skill is the metadata half; they share a release date and nothing else.
- admin/deployment-risk-assessment: Use to score a release's risk before you commit to a window. This skill assumes the go decision is made.
- admin/permission-sets-vs-profiles: Use when the release carries a Profile. It owns the overlay behaviour — a permission absent from the file is not revoked — and the strip-and-deploy ordering.
- devops/change-set-deployment: Use for Change Set mechanics: org connections, upload, immutability, Add Dependencies, and inbound-side errors.
- devops/metadata-api-retrieve-deploy: Use for the raw
retrieve()/deploy()call shapes and the zip/source layout. - devops/destructive-changes-deployment: Use when the release retires metadata and you need the full deletion workflow, not just the manifest shape.
- devops/pre-deployment-checklist: Use for the go/no-go gate immediately before the window.
- devops/post-deployment-validation: Use for the smoke-test design after the deploy reports success.
- devops/deployment-error-troubleshooting: Use when a deploy has already failed and you are reading
componentFailures. - devops/release-management: Use for the cross-release cadence, branching, and the mechanics of watching a quick-deploy job id.
- devops/migration-from-change-sets-to-sfdx: Use when the decision matrix says move off Change Sets and you need the migration path.