mcpField
P
platform-deploy-validate

platform-deploy-validate

github.com/forcedotcomCloud & DevOps1.1k3.1k installsUpdated 1d ago
Repository

About platform-deploy-validate

A Salesforce deployment-validation skill for teams preparing metadata changes. It selects a dry run or production validation based on the target org, and preserves production job IDs for `platform-quick-deploy`.

Key features

  1. 01Choose validation path by org type
  2. 02Dry-run sandbox and scratch deployments
  3. 03Validate production deployments with tests
  4. 04Save job IDs for quick deploy
  5. 05Summarize component and test failures

Use cases

  1. 01Validate metadata before a production deployment
  2. 02Check a sandbox deployment without changing the org
  3. 03Triage component or test errors from validation

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/forcedotcom/sf-skills --skill platform-deploy-validate

After installing, type/platform-deploy-validatein Claude Code to confirm it loaded.

Details

From the project README

Validating Deployment

Run a server-side validation before deploying metadata. Validation surfaces errors without modifying the org and — for production targets — produces a job ID usable with platform-quick-deploy for a fast, test-free deploy.

Capability Resolution

Always prefer sf project deploy validate (prod) or sf project deploy start --dry-run (sandbox/scratch) over the Tooling API directly.

Workflow

Step 1 — Confirm the target org

Classify the org with the gate's classifier — it is the authoritative source of truth and resolves the org the same way the deploy hook does (it handles sandbox/scratch markers, trial and Developer Edition orgs including SDOs, and treats a Dev Hub with no such signal as production; returns one of production|sandbox|scratch|trial|unknown):

"${CLAUDE_PLUGIN_ROOT}/scripts/sf-deploy-gate" bucket <alias>

Only production takes the production path (Step 2b); every other result takes the sandbox/scratch path (Step 2a). unknown means the org type could not be confirmed (usually an incomplete org record). Say so plainly: the deploy gate still allows the deploy, auto-deploy on save stays off for that org, and re-authenticating with sf org login web usually restores the classification.

Step 2a — Sandbox/Scratch path (dry-run)
sf project deploy start --dry-run --target-org <alias> --json [scope flags]

Scope flags (use exactly one, not all):

  • --source-dir <path> — deploy a directory
  • --metadata <Type:Name> — deploy specific components
  • --manifest manifest/package.xml — deploy from manifest

Default test level: omit --test-level for sandboxes (defers to org default). Add --test-level RunLocalTests only if the user asks.

Report back: success/failure, components attempted, any errors. No job ID is returned for dry-runs (this is expected).

Step 2b — Production path (validate)
sf project deploy validate --target-org <alias> --json [scope flags] --test-level RunLocalTests

Production validations REQUIRE a test level. Use RunLocalTests by default; switch to RunSpecifiedTests --tests <ClassName>... if the user has explicitly listed tests.

The response returns a job ID (result.id) valid for 10 days. Persist it for platform-quick-deploy:

mkdir -p .sfdx
echo '{"jobId":"<id>","createdAt":"<iso8601>","targetOrg":"<alias>","testLevel":"RunLocalTests"}' > .sfdx/last-validation.json

Report:

  • Validation result (passed / failed)
  • Job ID and 10-day expiry date
  • Test results summary (run / passed / failed)
  • Recommended next step: platform-quick-deploy with this job ID
Step 3 — Failure triage

If validation fails, parse result.details.componentFailures and result.details.runTestResult.failures and surface:

  • Top 5 component errors with full message
  • Top 5 test failures with stack
  • Suggested fix (component name → likely cause: missing dependency, FLS, syntax, etc.)

Do NOT propose fixes that change unrelated metadata. Stay scoped to what the validation reported.

Rules

  • ALWAYS use --json on every CLI call
  • NEVER skip validation when targeting Production (do not run sf project deploy start against prod from this skill)
  • NEVER use --ignore-errors or --ignore-warnings during validation; those flags belong to actual deploys, not validation
  • If the user asks to "deploy to prod" without prior validation, FIRST run validation, THEN hand off to platform-quick-deploy (do not start a regular deploy against prod)
  • Persist the validation job ID to .sfdx/last-validation.json so the quick-deploy skill can find it

Output

Always end with:

  • ✅ Validation passed → next-step pointer to platform-quick-deploy (with job ID + expiry) OR to platform-metadata-deploy for non-prod
  • ❌ Validation failed → categorized error list and suggested next iteration

Comments

Markdown supported