Use this skill to drive the full DevOps Center promotion workflow for work items and pipeline stages — validate preconditions, prepare work items, optionally combine work items that share metadata, promote one or more work items or an entire stage to a target pipeline stage, and complete the promoti

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: 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 : 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: 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 ): Then combine using those derived values (skip this command entirely when COMBINE is not "true" ): 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: Or promote all approved work items from a source stage (again, include the skip validation line only if Phase 1 validate passed this session): 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: 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 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

dx-devops-promote