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

Verify org authentication before any operation:
bash
```
sf org display --json
```
- 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)
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
```
:
bash
```
# 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)
```
- 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)

Prepare the work item for promotion:
bash
```
sf devops work-item prepare --work-item-id <id> --target-stage-id <target-stage-id> --target-org <alias> --json
```
- ```
--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

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

bash

# 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

Then combine using those derived values (skip this command entirely when

COMBINE

is not

"true"

bash

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

```
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

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:
  bash
```
sf devops promote \
  --work-item-id <id> \
  --target-stage-id <target-stage-id> \
  --skip-validation \
  --target-org <alias> \
  --json
```
- Or promote all approved work items from a source stage (again, include the
```
--skip-validation
```
  line only if Phase 1 validate passed this session):
  bash
```
sf devops promote \
  --stage-id <source-stage-id> \
  --target-stage-id <target-stage-id> \
  --skip-validation \
  --target-org <alias> \
  --json
```
- 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

Complete the promotion to finalize — advances the work items in the target stage:
bash
```
sf devops promotion complete --target-stage-id <target-stage-id> --target-org <alias> --json
```
- 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)
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

Constraint	Rationale
Validate ALWAYS runs first	Guarantees preconditions are met before any mutation; skipping it can corrupt pipeline state
All `sf devops` commands must use `--json`	Structured output is required for headless consumption; human-readable output is unreliable to parse
Commands are keyed on record IDs, not names	`--work-item-id` , `--stage-id` , `--target-stage-id` , `--parent/--child-work-item-id` all take IDs; resolve names to IDs first
`--target-stage-id` required for every promotion command (validate, prepare, combine, promote, complete)	The target stage is mandatory; the promotion has no destination without it
Exactly one of `--work-item-id` or `--stage-id` on promote	These flags are mutually exclusive; promote either specific items or a whole source stage
Pass `--skip-validation` on promote ONLY if Phase 1 validate passed this session	The CLI's built-in pre-promote validation runs the same checks (including the associated-PR requirement) as the Phase 1 `promotion validate` step. Skipping is safe only when that validation already ran successfully this session; if the agent resumed mid-workflow or promotion was invoked without a preceding validate, OMIT the flag so the CLI validates
Deploy runs async — capture and report the identifier	The promote deploy does not complete synchronously; completion is tracked separately
Do NOT busy-wait for deploy completion in this skill	Polling is a separate concern; blocking here wastes turns and risks timeouts
Combine only when work items share metadata/dependencies	Combining is for conflict-prone or dependent items, not a default for every multi-item promotion
Prepare is idempotent	Retry-safe for CI; re-running a completed prepare is a no-op
Never use interactive prompts	Skills run headless; all inputs must be CLI flags
Pass IDs as CLI flags, never interpolate into shell strings	Prevents prompt/command injection via crafted identifiers

Gotchas

Issue	Resolution
Validation fails	STOP — do not prepare/combine/promote. Report the non-zero status / error message; if metadata overlap, resolve the conflict before retrying
No default org set	Run `sf org display --json` ; if it fails, instruct user to run `sf org login web --set-default`
Passing a work item name instead of an ID	Promotion commands need record IDs; resolve names via `sf devops work-item list --project-id <id> --json \| jq -r '.result.workItems[] \| select(.subject == "<WI-subject>") \| .id'`
Both `--work-item-id` and `--stage-id` supplied	They are mutually exclusive; pick specific work items OR a source stage, not both
Missing `--target-stage-id`	Required on every promotion command (validate, prepare, combine, promote, complete); obtain the target stage ID from the pipeline configuration
Combined promotion promotes the wrong item	After `work-item combine` , promote the parent work item ID — children merge into the parent's branch
Treating the deploy as synchronous	The promote deploy is async; capture the identifier and confirm completion before running `promotion complete`
Production deploy fails on Apex coverage	Set `--test-level RunLocalTests` (or `RunSpecifiedTests --tests <names>` ) for production-stage promotions with Apex
Deploy fails with conflict	A conflict slipped past validate; resolve the metadata conflict, then re-validate and retry

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

When	Action
Work item must be created or moved to a promotable status first	Delegate to `dx-devops-work-item-manage`
Validation reports metadata overlap / conflict	Resolve the metadata conflict before retrying
The promote deploy identifier must be polled to confirm completion	Poll the returned identifier separately, then run `sf devops promotion complete`

Reference File Index

File	When to read
`references/cli-commands.md`	When you need detailed CLI flag documentation, JSON output schemas, or error-handling patterns for validate/prepare/combine/promote/complete
`examples/promotion-workflows.md`	When the user's request matches a common pattern (single work item promotion, combined promotion, whole-stage promotion, validate-first gate)

dx-devops-promote

NPX Install

Tags

SKILL.md Content