dx-devops-promote

DevOps Center 晋升

驱动 DevOps Center 中的完整晋升工作流——验证、准备、按需合并、晋升并完成——推动工作项沿发布流水线流转。提供由 --json 驱动的无头、幂等操作，适用于 CI 中的自主发布工作流。每次晋升都必须先执行验证。

范围

• 范围内：验证晋升前提条件、准备工作项、将共享元数据的工作项合并为一次晋升、将一个或多个工作项或整个源阶段晋升到目标阶段，以及完成晋升
• 范围外：创建工作项／更新工作项状态（使用 dx-devops-work-item-manage）、冲突检测、轮询现有晋升的状态、流水线或项目设置（使用单独的技能）

---

必需输入

继续操作前，请收集或推断以下信息：

• 晋升目标：一个或多个指定工作项，或源阶段中的所有已批准工作项
• 目标阶段 ID（每个晋升命令都必需，包括 validate、prepare、combine、promote 和 complete）：--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 后即可继续。

---

工作流

所有操作均使用带有 --json 输出的 sf devops CLI 命令。必须始终先运行 Validate。所有晋升命令都以记录 ID为依据，而非工作项名称——如有需要，请先将名称解析为 ID。

阶段 1 — 身份验证与验证

1. 在执行任何操作前，验证组织身份验证状态：

   sf org display --json
   

   • 如果失败，请指示用户运行 sf org login web --set-default --alias <alias>
   • 后续每条命令都传入 --target-org <alias>（必需，除非已设置 target-org 配置变量）

2. 运行必需的 validate 步骤——此步骤不可跳过，且必须始终在 prepare/combine/promote 之前运行。sf devops promotion validate 需要目标阶段（-t/--target-stage-id）和一个或多个 -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)
   

   • 验证工作项是否可以晋升到目标阶段——在尝试晋升之前检查 VCS 和对象权限错误（包括关联 PR 要求）
   • 可在一次调用中重复指定 --work-item-id，以验证多个工作项
   • 成功：status == 0 且 .result.success == true——继续
   • 如果验证失败（退出码非零；例如 VCS_ERROR: No pull request exists…，且已设置 .result.errorType／.result.errorDetails），请停止。报告错误，不要继续。如果错误提及元数据重叠，请先解决冲突再重试
   • **共享组件：**当 .result.combineDetails 不为 null 时，表示工作项共享元数据——validate 会返回父／子分组及 suggestions。这是阶段 2 合并决策的权威信号（见第 4 步）；不要猜测是否需要合并——阶段 2 脚本会读取 VALIDATE_JSON 中的 .result.combineDetails

阶段 2 — 准备（并可选择合并）

3. 准备要晋升的工作项：

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

   • 必须提供 --target-stage-id — 与工作项将要晋升到的目标阶段相同
   • 幂等：重新运行已准备好的工作项是安全的 — 将其视为成功

4. 合并工作项 — 仅当阶段 1 的 validate 步骤报告了共享组件（.result.combineDetails 非 null），或工作项存在依赖关系且必须作为一个整体晋升时才执行。不要凭直觉判断 JSON — 根据已保存的 validate 输出（VALIDATE_JSON）确定决策以及父项/子项 ID：

   # 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
   

   然后使用这些推导出的值进行合并（当 COMBINE 不为 "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 会为每个子工作项展开为一组 --child-work-item-id <id> 参数
   • 父项工作项是继续通过流水线的主要工作项；晋升期间，子项更改会合并到父项的分支中
   • 合并后，在步骤 5 中晋升父项工作项 ID

阶段 3 — 晋升

5. 晋升到目标阶段 — 必须提供 --work-item-id 或 --stage-id 中的一个，且只能提供其中一个；始终必须提供 --target-stage-id。仅当本次会话中阶段 1 的 validate 步骤已对每个待晋升的工作项成功完成时，才传入 --skip-validation。 否则，省略该标记，让 CLI 运行内置验证：
   • 晋升一个或多个指定工作项（每个工作项重复使用一次 --work-item-id；合并晋升时使用父项的 ID）。仅当本次会话中阶段 1 的 validate 通过时才包含 --skip-validation 行；否则删除该行：

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

   • 或晋升源阶段中的所有已批准工作项（同样，仅当本次会话中阶段 1 的 validate 通过时才包含 --skip-validation 行）：

     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 只是避免冗余的重复运行。但如果 Agent 在工作流中途恢复、在没有先运行阶段 1 validate 的情况下调用晋升，或阶段 1 并未针对每个待晋升的工作项运行，则不要传入 --skip-validation — 在这种情况下跳过验证会完全绕过验证，且没有事先的保障
   • 添加 --deploy-all，以部署分支中的所有元数据，而不仅是尚未进入目标阶段的更改
   • 对于包含 Apex 的生产阶段部署，添加 --test-level RunLocalTests（或 RunSpecifiedTests --tests <names>）
   • 部署会异步运行 — 从 JSON .result 中获取返回的晋升/部署 ID

阶段 4 — 完成并报告

6. 完成晋升以最终确认 — 推进目标阶段中的工作项：

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

   • 晋升部署成功后运行此步骤，以在目标阶段标记晋升已完成
   • 必须提供 --target-stage-id（与工作项晋升到的目标阶段相同）

7. 报告结果：

   • 确认 CLI 每个步骤都返回状态码 0
   • 报告晋升/部署 ID，并说明异步部署完成状态会单独跟踪
   • 不要在此技能中阻塞或忙等 — 显示该 ID 并返回
   • 清楚说明晋升情况，例如：“工作项晋升已启动（源阶段 → 目标阶段）。部署 ID：。请轮询此 ID 以确认部署完成，然后运行 promotion complete。”

---

规则 / 约束

约束	原因
始终先运行 Validate	确保在进行任何更改之前满足前置条件；跳过可能会破坏流水线状态
所有 sf devops 命令都必须使用 --json	无头环境需要结构化输出；人类可读输出不便于可靠解析
命令使用记录 ID，而非名称	--work-item-id、--stage-id、--target-stage-id、--parent/--child-work-item-id 都需要 ID；先将名称解析为 ID
每条晋级命令（validate、prepare、combine、promote、complete）都必须指定 --target-stage-id	目标阶段为必填项；没有目标阶段，晋级就没有目的地
promote 时，--work-item-id 和 --stage-id 必须且只能指定一个	这些标志互斥；promote 可以针对指定工作项，也可以针对整个源阶段
仅当本次会话中 Phase 1 validate 已通过时，才在 promote 时传入 --skip-validation	CLI 内置的晋级前验证会运行与 Phase 1 promotion validate 步骤相同的检查（包括关联 PR 要求）。只有在本次会话中已成功运行该验证时，跳过才安全；如果 Agent 在工作流中途恢复，或未先运行 validate 就调用晋级，则不要传入此标志，让 CLI 执行验证
部署以异步方式运行——捕获并报告标识符	promote 部署不会同步完成；完成情况需要单独跟踪
此技能中不要忙等部署完成	轮询属于单独的工作；在此处阻塞会浪费轮次并增加超时风险
仅当工作项共享元数据 / 依赖项时才执行 Combine	Combine 用于存在冲突风险或有依赖关系的工作项，不是每次多项晋级的默认操作
Prepare 是幂等的	对 CI 来说可安全重试；重复运行已完成的 prepare 不会产生影响
绝不使用交互式提示	技能以无头方式运行；所有输入都必须通过 CLI 标志提供
将 ID 作为 CLI 标志传入，绝不将其插入 Shell 字符串	防止通过精心构造的标识符进行提示词 / 命令注入

---

注意事项

问题	解决方法
验证失败	停止——不要执行 prepare/combine/promote。报告非零状态码 / 错误消息；如果是元数据重叠导致的问题，请先解决冲突再重试
未设置默认组织	运行 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' 解析名称
同时提供 --work-item-id 和 --stage-id	它们互斥；只能选择指定工作项或源阶段，不能两者兼选
缺少 --target-stage-id	每条晋级命令（validate、prepare、combine、promote、complete）都必须指定；从流水线配置中获取目标阶段 ID
Combine 晋级了错误的工作项	work-item combine 后，晋级父工作项 ID——子项会合并到父项的分支中
将部署视为同步操作	promote 部署是异步的；捕获标识符，并在运行 promotion complete 前确认部署已完成
生产部署因 Apex 覆盖率而失败	对包含 Apex 的生产阶段晋级，设置 --test-level RunLocalTests（或使用 RunSpecifiedTests --tests <names>）
部署因冲突而失败	验证时遗漏了冲突；解决元数据冲突后，重新验证并重试

---

输出预期

各项操作的交付内容有所不同：

• Validate：.result.success，以及在工作项共享元数据时返回的 .result.combineDetails / .result.suggestions。非零退出代码（包含 .result.errorType/.result.errorDetails）表示该工作项无法晋升到目标阶段
• Prepare / combine：确认工作项已暂存（combine 会返回父项/子项分组）
• Promote：异步部署标识符，以及已启动晋升部署的确认
• Promotion complete：确认工作项已进入目标阶段

输出源自 sf devops work-item、sf devops promote 和 sf devops promotion complete CLI 命令。promote 调用不会返回异步部署完成状态——请单独轮询返回的标识符，然后再完成操作。

---

跨技能集成

何时	操作
必须先创建工作项或将其移至可晋升状态	委派给 dx-devops-work-item-manage
验证报告存在元数据重叠/冲突	解决元数据冲突后重试
必须轮询 promote 部署标识符以确认完成	单独轮询返回的标识符，然后运行 sf devops promotion complete

---

参考文件索引

文件	何时阅读
references/cli-commands.md	需要了解详细的 CLI 标志文档、JSON 输出架构，或 validate/prepare/combine/promote/complete 的错误处理模式时
examples/promotion-workflows.md	用户的请求符合常见模式（单个工作项晋升、组合晋升、整个阶段晋升、先验证再执行的关卡）时