kris/afv-library
1
0
Fork 0
mirror of https://github.com/forcedotcom/afv-library.git synced 2026-08-09 08:53:18 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
e57cbefbfe
afv-library/skills/dx-devops-promote/SKILL.md

15 KiB
Raw Blame History

name description metadata
dx-devops-promote 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 promotion to finalize the deployment. TRIGGER when the user wants to promote a work item, advance changes to the next environment or stage, combine work items for a single promotion, or move metadata through the release pipeline. The mandatory validate step runs automatically at the start. DO NOT TRIGGER for work item creation or status updates (use dx-devops-work-item-manage), for conflict detection, or for polling an existing promotion's status.
version minApiVersion relatedSkills cliTools accessCheck
1.0 58.0
dx-devops-work-item-manage
tool semver
jq
>=1.6
tool semver
sf
>=2.0.0
type value
orgPref ALMDevopsCorePref
type value
userPerm UserHasDevOpsCore

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
    • 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)
    • 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)

  1. 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
    • --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

  2. 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

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

  1. 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
    • 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
    • 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

  1. 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
    • 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)

  2. 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: . 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)