DevOps Center Promotion

Drives the full promotion workflow in DevOps Center — validate, prepare, optionally combine, promote, and complete — moving work items through the release pipeline. Provides headless, --json-driven, idempotent operations for autonomous release workflows in CI. Every promotion begins with a mandatory validate step.

Scope

• In scope: Validate promotion preconditions, prepare a work item, combine work items that share metadata into one promotion, promote one or more work items or an entire source stage to a target stage, and complete the promotion
• Out of scope: Work item creation/status updates (use dx-devops-work-item-manage), conflict detection, polling an existing promotion's status, pipeline or project setup (separate skills)

---

Required Inputs

Gather or infer before proceeding:

• Promotion target: one or more specific work items, or all approved work items in a source stage
• Target stage ID (required for every promotion command — validate, prepare, combine, promote, and complete): --target-stage-id — the pipeline stage to promote to
• Work item ID(s) or source stage ID — depending on the promotion target. sf devops promote takes --work-item-id (repeatable) XOR --stage-id
• For combined promotion: a parent work item ID and one or more child work item IDs that share metadata
• Target org: --target-org <alias> (required unless the target-org config variable is set)

Defaults unless specified:

• Output format: --json for headless consumption
• Test level: omit --test-level for development-stage deploys (defaults to NoTestRun); use RunLocalTests for production-stage deploys with Apex

If the user gives a clear request ("promote work item 1fkxx… to stage 1QVxx…", "promote the QA stage to UAT", "combine these work items and promote"), proceed once you have the required IDs.

---

Workflow

All operations use sf devops CLI commands with --json output. Validate ALWAYS runs first. All promotion commands are keyed on record IDs, not work item names — resolve names to IDs first if needed.

Phase 1 — Authenticate and Validate

1. Verify org authentication before any operation:

   sf org display --json
   

   Copy
   • If it fails, instruct the user to run sf org login web --set-default --alias <alias>
   • Pass --target-org <alias> on every subsequent command (required unless the target-org config variable is set)

2. Run the mandatory validate step — this is non-negotiable and always runs before prepare/combine/promote. sf devops promotion validate requires the target stage (-t/--target-stage-id) and one or more -i/--work-item-id:

   # Capture the output — Phase 2 derives the combine decision from it deterministically.
   VALIDATE_JSON=$(sf devops promotion validate --work-item-id <id> --target-stage-id <target-stage-id> --target-org <alias> --json)
   

   Copy
   • Validates whether the work item(s) can be promoted to the target stage — checks for VCS and object-permission errors (including the associated-PR requirement) before a promotion is attempted
   • Repeat --work-item-id to validate multiple work items in one call
   • Success: status == 0 and .result.success == true — proceed
   • If validation fails (non-zero exit; e.g. VCS_ERROR: No pull request exists…, with .result.errorType/.result.errorDetails set), STOP. Report the error and do not proceed. If it references metadata overlap, resolve the conflict before retrying
   • Shared components: when .result.combineDetails is non-null, the work items share metadata — validate returns the parent/child grouping and suggestions. This is the authoritative signal for the Phase 2 combine decision (see step 4); do not guess whether to combine — the Phase 2 script reads .result.combineDetails from VALIDATE_JSON

Phase 2 — Prepare (and optionally Combine)

3. Prepare the work item for promotion:

   sf devops work-item prepare --work-item-id <id> --target-stage-id <target-stage-id> --target-org <alias> --json
   

   Copy
   • --target-stage-id is required — the same target stage the work item will be promoted to
   • Idempotent: re-running a prepared work item is safe — treat as success

4. Combine work items — ONLY when the Phase 1 validate step reported shared components (.result.combineDetails non-null) or the work items otherwise have dependencies and must promote as one unit. Do not eyeball the JSON — derive the decision and the parent/child IDs deterministically from the saved validate output (VALIDATE_JSON):

   # COMBINE == "true" only when validate returned a combineDetails block.
   COMBINE=$(printf '%s' "$VALIDATE_JSON" | jq -r '(.result.combineDetails != null)')
   if [ "$COMBINE" = "true" ]; then
     PARENT_ID=$(printf '%s' "$VALIDATE_JSON" | jq -r '.result.combineDetails.parentWorkitemId')
     # one --child-work-item-id arg per child, safe for use as a flag array
     CHILD_ARGS=()
     while IFS= read -r cid; do CHILD_ARGS+=(--child-work-item-id "$cid"); done < <(
       printf '%s' "$VALIDATE_JSON" | jq -r '.result.combineDetails.childWorkitemsId[]')
   fi
   

   Copy

   Then combine using those derived values (skip this command entirely when COMBINE is not "true"):

   sf devops work-item combine \
     --parent-work-item-id "$PARENT_ID" \
     "${CHILD_ARGS[@]}" \
     --target-stage-id <stage-id> \
     --target-org <alias> \
     --json
   

   Copy
   • CHILD_ARGS expands to one --child-work-item-id <id> pair per child work item
   • The parent work item is the primary item that continues through the pipeline; child changes merge into the parent's branch during promotion
   • After combining, promote the parent work item ID in step 5

Phase 3 — Promote

5. Promote to the target stage — exactly one of --work-item-id or --stage-id must be provided; --target-stage-id is always required. Pass --skip-validation ONLY when the Phase 1 validate step completed successfully in the current session for every work item being promoted. Otherwise, OMIT the flag and let the CLI run its built-in validation:
   • Promote one or more specific work items (repeat --work-item-id per item; use the parent's ID for a combined promotion). Include the --skip-validation line ONLY if Phase 1 validate passed this session; otherwise drop that line:

     sf devops promote \
       --work-item-id <id> \
       --target-stage-id <target-stage-id> \
       --skip-validation \
       --target-org <alias> \
       --json
     

     Copy
   • Or promote all approved work items from a source stage (again, include the --skip-validation line only if Phase 1 validate passed this session):

     sf devops promote \
       --stage-id <source-stage-id> \
       --target-stage-id <target-stage-id> \
       --skip-validation \
       --target-org <alias> \
       --json
     

     Copy
   • Why conditional: sf devops promote's built-in pre-promote validation runs the same checks as the Phase 1 sf devops promotion validate step (including the associated-PR requirement). When the full workflow ran sequentially this session, that validation already passed, so --skip-validation only eliminates a redundant re-run. But if the agent resumed mid-workflow, promotion was invoked without a preceding Phase 1 validate, or Phase 1 was not run for every work item being promoted, DO NOT pass --skip-validation — bypassing it there would skip validation entirely with no prior guard
   • Add --deploy-all to deploy all metadata in the branch rather than only changes not yet in the target stage
   • Add --test-level RunLocalTests (or RunSpecifiedTests --tests <names>) for production-stage deploys that include Apex
   • The deploy runs asynchronously — capture the returned promotion/deploy identifier from the JSON .result

Phase 4 — Complete and Report

6. Complete the promotion to finalize — advances the work items in the target stage:

   sf devops promotion complete --target-stage-id <target-stage-id> --target-org <alias> --json
   

   Copy
   • Run after the promote deploy succeeds to mark the promotion done in the target stage
   • --target-stage-id is required (same target stage the work items were promoted to)

7. Report the outcome:

   • Confirm the CLI returned status 0 for each step
   • Report the promotion/deploy identifier and note that async deploy completion is tracked separately
   • Do NOT block or busy-wait inside this skill — surface the identifier and return
   • State the promotion clearly: e.g., "Work item promotion initiated (source stage → target stage). Deploy ID: <id>. Poll this ID to confirm deploy completion, then run promotion complete."

---

Rules / Constraints

---

Gotchas

---

Output Expectations

Deliverables vary by operation:

• Validate: .result.success plus, when work items share metadata, .result.combineDetails / .result.suggestions. A non-zero exit (with .result.errorType/.result.errorDetails) means the work item cannot be promoted to the target stage
• Prepare / combine: confirmation that the work item(s) are staged (combine returns the parent/child grouping)
• Promote: an async deploy identifier and confirmation that the promotion deploy was initiated
• Promotion complete: confirmation the work items advanced in the target stage

Outputs are derived from sf devops work-item, sf devops promote, and sf devops promotion complete CLI commands. Async deploy completion is NOT produced by the promote call — poll the returned identifier separately before completing.

---

Cross-Skill Integration

---

Reference File Index