dx-devops-promote

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DevOps Center Promotion

DevOps Center推广

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.
驱动DevOps Center中的完整推广工作流——验证、准备、可选合并、推广和完成——将工作项通过发布流水线推进。为CI中的自主发布工作流提供无界面、
--json
驱动的幂等操作。每次推广都从强制性的验证步骤开始。

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)

  • 适用场景:验证推广前置条件、准备工作项、将共享元数据的工作项合并为一次推广、将一个或多个工作项或整个源阶段推广到目标阶段、完成推广
  • 不适用场景:工作项创建/状态更新(使用
    dx-devops-work-item-manage
    )、冲突检测、轮询现有推广状态、流水线或项目设置(由其他独立技能处理)

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.

执行前需收集或推断:
  • 推广目标:一个或多个特定工作项,或源阶段中所有已批准的工作项
  • 目标阶段ID(所有推广命令——验证、准备、合并、推广、完成——均必填):
    --target-stage-id
    —— 要推广到的流水线阶段
  • 工作项ID源阶段ID —— 取决于推广目标。
    sf devops promote
    命令需使用
    --work-item-id
    (可重复使用)或
    --stage-id
    ,二者选其一
  • 合并推广时:一个父工作项ID和一个或多个共享元数据的子工作项ID
  • 目标组织
    --target-org <alias>
    (除非已设置
    target-org
    配置变量,否则必填)
默认设置(未指定时):
  • 输出格式:
    --json
    ,用于无界面场景消费
  • 测试级别:开发阶段部署可省略
    --test-level
    (默认值为
    NoTestRun
    );包含Apex的生产阶段部署使用
    RunLocalTests
如果用户给出明确请求(如“将工作项1fkxx…推广到阶段1QVxx…”、“将QA阶段推广到UAT”、“合并这些工作项并推广”),获取必填ID后即可执行。

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.
所有操作均使用带
--json
输出的
sf devops
CLI命令。验证步骤始终首先执行。所有推广命令均以记录ID为关键标识,而非工作项名称——如有需要,先将名称解析为ID。

Phase 1 — Authenticate and Validate

阶段1 — 身份验证与验证

  1. 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)
  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
    :
    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
  1. 在任何操作前验证组织身份验证
    bash
    sf org display --json
    • 如果验证失败,指导用户运行
      sf org login web --set-default --alias <alias>
    • 在后续所有命令中传递
      --target-org <alias>
      (除非已设置
      target-org
      配置变量,否则必填)
  2. 执行强制性验证步骤——这是不可协商的,必须在准备/合并/推广前运行。
    sf devops promotion validate
    命令需要目标阶段(
    -t/--target-stage-id
    )和一个或多个
    -i/--work-item-id
    bash
    # 捕获输出——阶段2将根据输出确定是否需要合并。
    VALIDATE_JSON=$(sf devops promotion validate --work-item-id <id> --target-stage-id <target-stage-id> --target-org <alias> --json)
    • 验证工作项是否可推广到目标阶段——在尝试推广前检查VCS和对象权限错误(包括关联PR要求)
    • 重复使用
      --work-item-id
      可在一次调用中验证多个工作项
    • 成功
      status == 0
      .result.success == true
      —— 继续执行
    • 验证失败(非零退出码;例如
      VCS_ERROR: No pull request exists…
      ,且
      .result.errorType
      /
      .result.errorDetails
      已设置):停止执行。报告错误,不得继续。如果错误涉及元数据重叠,解决冲突后再重试
    • 共享组件:当
      .result.combineDetails
      不为空时,说明工作项共享元数据——验证结果会返回父/子分组和
      suggestions
      。这是阶段2合并决策的权威信号(见步骤4);请勿自行判断是否合并——阶段2脚本会从
      VALIDATE_JSON
      中读取
      .result.combineDetails

Phase 2 — Prepare (and optionally Combine)

阶段2 — 准备(可选合并)

  1. 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
  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
    ):
    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
  1. 为推广准备工作项
    bash
    sf devops work-item prepare --work-item-id <id> --target-stage-id <target-stage-id> --target-org <alias> --json
    • --target-stage-id
      为必填项——与工作项将要推广到的目标阶段一致
    • 幂等性:重新运行已准备好的工作项是安全的——视为成功
  2. 合并工作项——仅当阶段1验证步骤报告存在共享组件(
    .result.combineDetails
    不为空)或工作项存在依赖关系必须作为一个单元推广时执行。请勿手动分析JSON——从保存的验证输出(
    VALIDATE_JSON
    )中确定是否合并以及父/子ID:
    bash
    # 仅当验证返回combineDetails块时,COMBINE == "true"。
    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')
      # 每个子项对应一个--child-work-item-id参数,可安全用作标志数组
      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
    然后使用推导的值执行合并(当
    COMBINE
    不为
    "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
      会展开为每个子工作项对应的
      --child-work-item-id <id>
      参数对
    • 工作项是继续在流水线中推进的主要项;子项变更会在推广期间合并到父项的分支中
    • 合并后,在步骤5中推广工作项ID

Phase 3 — Promote

阶段3 — 推广

  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:
      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
  1. 推广到目标阶段——必须提供
    --work-item-id
    --stage-id
    中的一个;
    --target-stage-id
    始终为必填项。仅当阶段1验证步骤在当前会话中对所有要推广的工作项均执行成功时,才传递
    --skip-validation
    。否则,省略该标志,让CLI运行内置验证:
    • 推广一个或多个特定工作项(每个项重复使用
      --work-item-id
      ;合并推广时使用父项ID)。仅当阶段1验证在本次会话中通过时,才添加
      --skip-validation
      行;否则删除该行:
      bash
      sf devops promote \
        --work-item-id <id> \
        --target-stage-id <target-stage-id> \
        --skip-validation \
        --target-org <alias> \
        --json
    • 或推广源阶段中所有已批准的工作项(同样,仅当阶段1验证在本次会话中通过时,才添加
      --skip-validation
      行):
      bash
      sf devops promote \
        --stage-id <source-stage-id> \
        --target-stage-id <target-stage-id> \
        --skip-validation \
        --target-org <alias> \
        --json
    • 条件原因
      sf devops promote
      的内置推广前验证会执行与阶段1
      sf devops promotion validate
      步骤相同的检查(包括关联PR要求)。当完整工作流在本次会话中连续执行时,该验证已通过,因此
      --skip-validation
      仅能消除重复执行。但如果代理在工作流中途恢复、未执行阶段1验证就调用推广,或阶段1未对所有要推广的工作项执行验证,则请勿传递
      --skip-validation
      ——此时跳过验证会完全绕过前置检查
    • 添加
      --deploy-all
      可部署分支中的所有元数据,而非仅部署目标阶段中尚未存在的变更
    • 对于包含Apex的生产阶段部署,添加
      --test-level RunLocalTests
      (或
      RunSpecifiedTests --tests <names>
    • 部署为异步执行——从JSON
      .result
      中捕获返回的推广/部署标识符

Phase 4 — Complete and Report

阶段4 — 完成与报告

  1. 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)
  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: <id>. Poll this ID to confirm deploy completion, then run promotion complete."

  1. 完成推广以最终确定——推进目标阶段中的工作项:
    bash
    sf devops promotion complete --target-stage-id <target-stage-id> --target-org <alias> --json
    • 在推广部署成功后运行,以标记目标阶段中的推广完成
    • --target-stage-id
      为必填项(与工作项推广到的目标阶段一致)
  2. 报告结果
    • 确认每个步骤的CLI返回状态码为0
    • 报告推广/部署标识符,并说明异步部署完成情况需单独跟踪
    • 请勿在此技能中阻塞或轮询——展示标识符后返回
    • 清晰说明推广情况:例如,“工作项推广已启动(源阶段 → 目标阶段)。部署ID:<id>。轮询此ID以确认部署完成,然后运行promotion complete。”

Rules / Constraints

规则/约束

ConstraintRationale
Validate ALWAYS runs firstGuarantees 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 identifierThe promote deploy does not complete synchronously; completion is tracked separately
Do NOT busy-wait for deploy completion in this skillPolling is a separate concern; blocking here wastes turns and risks timeouts
Combine only when work items share metadata/dependenciesCombining is for conflict-prone or dependent items, not a default for every multi-item promotion
Prepare is idempotentRetry-safe for CI; re-running a completed prepare is a no-op
Never use interactive promptsSkills run headless; all inputs must be CLI flags
Pass IDs as CLI flags, never interpolate into shell stringsPrevents prompt/command injection via crafted identifiers

约束理由
验证始终首先执行确保在任何变更操作前满足前置条件;跳过此步骤可能损坏流水线状态
所有
sf devops
命令必须使用
--json
结构化输出是无界面消费的必需条件;人类可读输出解析不可靠
命令以记录ID为关键标识,而非名称
--work-item-id
--stage-id
--target-stage-id
--parent/--child-work-item-id
均接受ID;先将名称解析为ID
所有推广命令(验证、准备、合并、推广、完成)均需
--target-stage-id
目标阶段是必填项;没有目标阶段,推广就没有目的地
推广命令必须且只能使用
--work-item-id
--stage-id
中的一个
这些标志互斥;要么推广特定项,要么推广整个源阶段,不可同时选择
仅当阶段1验证在本次会话中通过时,才在推广时传递
--skip-validation
CLI的内置推广前验证会执行与阶段1
promotion validate
步骤相同的检查(包括关联PR要求)。仅当该验证已在本次会话中成功执行时,跳过才是安全的;如果代理在工作流中途恢复或未执行前置验证就调用推广,则省略该标志,让CLI执行验证
部署为异步执行——捕获并报告标识符推广部署不会同步完成;完成情况需单独跟踪
请勿在此技能中轮询部署完成情况轮询是单独的任务;在此处阻塞会浪费执行次数并可能导致超时
仅当工作项共享元数据/存在依赖关系时才合并合并适用于易冲突或存在依赖的项,并非所有多项目推广的默认操作
准备操作具有幂等性对CI而言可安全重试;重新运行已完成的准备操作不会产生任何影响
切勿使用交互式提示技能以无界面方式运行;所有输入必须通过CLI标志提供
以CLI标志形式传递ID,切勿插入到shell字符串中防止通过精心构造的标识符进行提示/命令注入

Gotchas

常见问题

IssueResolution
Validation failsSTOP — do not prepare/combine/promote. Report the non-zero status / error message; if metadata overlap, resolve the conflict before retrying
No default org setRun
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 IDPromotion 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 itemAfter
work-item combine
, promote the parent work item ID — children merge into the parent's branch
Treating the deploy as synchronousThe promote deploy is async; capture the identifier and confirm completion before running
promotion complete
Production deploy fails on Apex coverageSet
--test-level RunLocalTests
(or
RunSpecifiedTests --tests <names>
) for production-stage promotions with Apex
Deploy fails with conflictA conflict slipped past validate; resolve the metadata conflict, then re-validate and retry

问题解决方法
验证失败停止执行——请勿进行准备/合并/推广操作。报告非零状态码/错误信息;如果涉及元数据重叠,解决冲突后再重试
未设置默认组织运行
sf org display --json
;如果失败,指导用户运行
sf org login web --set-default
传递工作项名称而非ID推广命令需要记录ID;通过
sf devops work-item list --project-id <id> --json | jq -r '.result.workItems[] | select(.subject == "<WI-subject>") | .id'
将名称解析为ID
同时提供
--work-item-id
--stage-id
二者互斥;选择特定工作项或源阶段,不可同时选择
缺少
--target-stage-id
所有推广命令(验证、准备、合并、推广、完成)均必填;从流水线配置中获取目标阶段ID
合并推广时推广了错误的项执行
work-item combine
后,推广工作项ID——子项会合并到父项的分支中
将部署视为同步操作推广部署是异步的;捕获标识符并确认完成后,再运行
promotion complete
生产部署因Apex覆盖率失败对于包含Apex的生产阶段推广,设置
--test-level RunLocalTests
(或
RunSpecifiedTests --tests <names>
部署因冲突失败冲突未被验证步骤检测到;解决元数据冲突后,重新验证并重试

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.

交付成果因操作而异:
  • 验证
    .result.success
    ,当工作项共享元数据时还会返回
    .result.combineDetails
    /
    .result.suggestions
    。非零退出码(带有
    .result.errorType
    /
    .result.errorDetails
    )表示工作项无法推广到目标阶段
  • 准备/合并:确认工作项已准备就绪(合并操作会返回父/子分组)
  • 推广:异步部署标识符,以及推广部署已启动的确认信息
  • 推广完成:确认工作项已在目标阶段中推进
输出来自
sf devops work-item
sf devops promote
sf devops promotion complete
CLI命令。异步部署完成情况不会由推广调用返回——需单独轮询返回的标识符,然后再执行完成操作。

Cross-Skill Integration

跨技能集成

WhenAction
Work item must be created or moved to a promotable status firstDelegate to
dx-devops-work-item-manage
Validation reports metadata overlap / conflictResolve the metadata conflict before retrying
The promote deploy identifier must be polled to confirm completionPoll the returned identifier separately, then run
sf devops promotion complete

场景操作
工作项必须先创建或移动到可推广状态委托给
dx-devops-work-item-manage
技能
验证报告元数据重叠/冲突解决元数据冲突后再重试
需轮询推广部署标识符以确认完成单独轮询返回的标识符,然后运行
sf devops promotion complete

Reference File Index

参考文件索引

FileWhen 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)
文件阅读时机
references/cli-commands.md
需要验证/准备/合并/推广/完成操作的详细CLI标志文档、JSON输出模式或错误处理模式时
examples/promotion-workflows.md
用户请求匹配常见模式(单个工作项推广、合并推广、全阶段推广、先验证再执行)时