dx-devops-promote
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDevOps 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, -driven, idempotent operations for autonomous release workflows in CI. Every promotion begins with a mandatory validate step.
--json驱动DevOps Center中的完整推广工作流——验证、准备、可选合并、推广和完成——将工作项通过发布流水线推进。为CI中的自主发布工作流提供无界面、驱动的幂等操作。每次推广都从强制性的验证步骤开始。
--jsonScope
适用范围
- 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 ), conflict detection, polling an existing promotion's status, pipeline or project setup (separate skills)
dx-devops-work-item-manage
- 适用场景:验证推广前置条件、准备工作项、将共享元数据的工作项合并为一次推广、将一个或多个工作项或整个源阶段推广到目标阶段、完成推广
- 不适用场景:工作项创建/状态更新(使用)、冲突检测、轮询现有推广状态、流水线或项目设置(由其他独立技能处理)
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): — the pipeline stage to promote to
--target-stage-id - Work item ID(s) or source stage ID — depending on the promotion target. takes
sf devops promote(repeatable) XOR--work-item-id--stage-id - For combined promotion: a parent work item ID and one or more child work item IDs that share metadata
- Target org: (required unless the
--target-org <alias>config variable is set)target-org
Defaults unless specified:
- Output format: for headless consumption
--json - Test level: omit for development-stage deploys (defaults to
--test-level); useNoTestRunfor production-stage deploys with ApexRunLocalTests
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);包含Apex的生产阶段部署使用NoTestRunRunLocalTests
如果用户给出明确请求(如“将工作项1fkxx…推广到阶段1QVxx…”、“将QA阶段推广到UAT”、“合并这些工作项并推广”),获取必填ID后即可执行。
Workflow
工作流
All operations use CLI commands with output. Validate ALWAYS runs first. All promotion commands are keyed on record IDs, not work item names — resolve names to IDs first if needed.
sf devops--json所有操作均使用带输出的 CLI命令。验证步骤始终首先执行。所有推广命令均以记录ID为关键标识,而非工作项名称——如有需要,先将名称解析为ID。
--jsonsf devopsPhase 1 — Authenticate and Validate
阶段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 on every subsequent command (required unless the
--target-org <alias>config variable is set)target-org
- If it fails, instruct the user to run
-
Run the mandatory validate step — this is non-negotiable and always runs before prepare/combine/promote.requires the target stage (
sf devops promotion validate) and one or more-t/--target-stage-id:-i/--work-item-idbash# 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 to validate multiple work items in one call
--work-item-id - Success: and
status == 0— proceed.result.success == true - If validation fails (non-zero exit; e.g. , with
VCS_ERROR: No pull request exists…/.result.errorTypeset), STOP. Report the error and do not proceed. If it references metadata overlap, resolve the conflict before retrying.result.errorDetails - Shared components: when is non-null, the work items share metadata — validate returns the parent/child grouping and
.result.combineDetails. This is the authoritative signal for the Phase 2 combine decision (see step 4); do not guess whether to combine — the Phase 2 script readssuggestionsfrom.result.combineDetailsVALIDATE_JSON
-
在任何操作前验证组织身份验证:bash
sf org display --json- 如果验证失败,指导用户运行
sf org login web --set-default --alias <alias> - 在后续所有命令中传递(除非已设置
--target-org <alias>配置变量,否则必填)target-org
- 如果验证失败,指导用户运行
-
执行强制性验证步骤——这是不可协商的,必须在准备/合并/推广前运行。命令需要目标阶段(
sf devops promotion validate)和一个或多个-t/--target-stage-id:-i/--work-item-idbash# 捕获输出——阶段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。这是阶段2合并决策的权威信号(见步骤4);请勿自行判断是否合并——阶段2脚本会从suggestions中读取VALIDATE_JSON.result.combineDetails
Phase 2 — Prepare (and optionally Combine)
阶段2 — 准备(可选合并)
-
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- is required — the same target stage the work item will be promoted to
--target-stage-id - 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 (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 (
.result.combineDetails):VALIDATE_JSONbash# 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[]') fiThen combine using those derived values (skip this command entirely whenis notCOMBINE):"true"bashsf devops work-item combine \ --parent-work-item-id "$PARENT_ID" \ "${CHILD_ARGS[@]}" \ --target-stage-id <stage-id> \ --target-org <alias> \ --json- expands to one
CHILD_ARGSpair per child work item--child-work-item-id <id> - 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
-
为推广准备工作项:bash
sf devops work-item prepare --work-item-id <id> --target-stage-id <target-stage-id> --target-org <alias> --json- 为必填项——与工作项将要推广到的目标阶段一致
--target-stage-id - 幂等性:重新运行已准备好的工作项是安全的——视为成功
-
合并工作项——仅当阶段1验证步骤报告存在共享组件(不为空)或工作项存在依赖关系必须作为一个单元推广时执行。请勿手动分析JSON——从保存的验证输出(
.result.combineDetails)中确定是否合并以及父/子ID:VALIDATE_JSONbash# 仅当验证返回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"bashsf 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 — 推广
- Promote to the target stage — exactly one of or
--work-item-idmust be provided;--stage-idis always required. Pass--target-stage-idONLY 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:--skip-validation- Promote one or more specific work items (repeat per item; use the parent's ID for a combined promotion). Include the
--work-item-idline ONLY if Phase 1 validate passed this session; otherwise drop that line:--skip-validationbashsf 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 line only if Phase 1 validate passed this session):
--skip-validationbashsf devops promote \ --stage-id <source-stage-id> \ --target-stage-id <target-stage-id> \ --skip-validation \ --target-org <alias> \ --json - Why conditional: 's built-in pre-promote validation runs the same checks as the Phase 1
sf devops promotestep (including the associated-PR requirement). When the full workflow ran sequentially this session, that validation already passed, sosf devops promotion validateonly 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--skip-validation - Add to deploy all metadata in the branch rather than only changes not yet in the target stage
--deploy-all - Add (or
--test-level RunLocalTests) for production-stage deploys that include ApexRunSpecifiedTests --tests <names> - The deploy runs asynchronously — capture the returned promotion/deploy identifier from the JSON
.result
- Promote one or more specific work items (repeat
- 推广到目标阶段——必须提供或
--work-item-id中的一个;--stage-id始终为必填项。仅当阶段1验证步骤在当前会话中对所有要推广的工作项均执行成功时,才传递--target-stage-id。否则,省略该标志,让CLI运行内置验证:--skip-validation- 推广一个或多个特定工作项(每个项重复使用;合并推广时使用父项ID)。仅当阶段1验证在本次会话中通过时,才添加
--work-item-id行;否则删除该行:--skip-validationbashsf devops promote \ --work-item-id <id> \ --target-stage-id <target-stage-id> \ --skip-validation \ --target-org <alias> \ --json - 或推广源阶段中所有已批准的工作项(同样,仅当阶段1验证在本次会话中通过时,才添加行):
--skip-validationbashsf devops promote \ --stage-id <source-stage-id> \ --target-stage-id <target-stage-id> \ --skip-validation \ --target-org <alias> \ --json - 条件原因:的内置推广前验证会执行与阶段1
sf devops promote步骤相同的检查(包括关联PR要求)。当完整工作流在本次会话中连续执行时,该验证已通过,因此sf devops promotion validate仅能消除重复执行。但如果代理在工作流中途恢复、未执行阶段1验证就调用推广,或阶段1未对所有要推广的工作项执行验证,则请勿传递--skip-validation——此时跳过验证会完全绕过前置检查--skip-validation - 添加可部署分支中的所有元数据,而非仅部署目标阶段中尚未存在的变更
--deploy-all - 对于包含Apex的生产阶段部署,添加(或
--test-level RunLocalTests)RunSpecifiedTests --tests <names> - 部署为异步执行——从JSON 中捕获返回的推广/部署标识符
.result
- 推广一个或多个特定工作项(每个项重复使用
Phase 4 — Complete and Report
阶段4 — 完成与报告
-
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
- is required (same target stage the work items were promoted to)
--target-stage-id
-
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."
-
完成推广以最终确定——推进目标阶段中的工作项:bash
sf devops promotion complete --target-stage-id <target-stage-id> --target-org <alias> --json- 在推广部署成功后运行,以标记目标阶段中的推广完成
- 为必填项(与工作项推广到的目标阶段一致)
--target-stage-id
-
报告结果:
- 确认每个步骤的CLI返回状态码为0
- 报告推广/部署标识符,并说明异步部署完成情况需单独跟踪
- 请勿在此技能中阻塞或轮询——展示标识符后返回
- 清晰说明推广情况:例如,“工作项推广已启动(源阶段 → 目标阶段)。部署ID:<id>。轮询此ID以确认部署完成,然后运行promotion complete。”
Rules / Constraints
规则/约束
| Constraint | Rationale |
|---|---|
| Validate ALWAYS runs first | Guarantees preconditions are met before any mutation; skipping it can corrupt pipeline state |
All | Structured output is required for headless consumption; human-readable output is unreliable to parse |
| Commands are keyed on record IDs, not names | |
| The target stage is mandatory; the promotion has no destination without it |
Exactly one of | These flags are mutually exclusive; promote either specific items or a whole source stage |
Pass | The CLI's built-in pre-promote validation runs the same checks (including the associated-PR requirement) as the Phase 1 |
| 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 |
| 约束 | 理由 |
|---|---|
| 验证始终首先执行 | 确保在任何变更操作前满足前置条件;跳过此步骤可能损坏流水线状态 |
所有 | 结构化输出是无界面消费的必需条件;人类可读输出解析不可靠 |
| 命令以记录ID为关键标识,而非名称 | |
所有推广命令(验证、准备、合并、推广、完成)均需 | 目标阶段是必填项;没有目标阶段,推广就没有目的地 |
推广命令必须且只能使用 | 这些标志互斥;要么推广特定项,要么推广整个源阶段,不可同时选择 |
仅当阶段1验证在本次会话中通过时,才在推广时传递 | CLI的内置推广前验证会执行与阶段1 |
| 部署为异步执行——捕获并报告标识符 | 推广部署不会同步完成;完成情况需单独跟踪 |
| 请勿在此技能中轮询部署完成情况 | 轮询是单独的任务;在此处阻塞会浪费执行次数并可能导致超时 |
| 仅当工作项共享元数据/存在依赖关系时才合并 | 合并适用于易冲突或存在依赖的项,并非所有多项目推广的默认操作 |
| 准备操作具有幂等性 | 对CI而言可安全重试;重新运行已完成的准备操作不会产生任何影响 |
| 切勿使用交互式提示 | 技能以无界面方式运行;所有输入必须通过CLI标志提供 |
| 以CLI标志形式传递ID,切勿插入到shell字符串中 | 防止通过精心构造的标识符进行提示/命令注入 |
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 |
| Passing a work item name instead of an ID | Promotion commands need record IDs; resolve names via |
Both | They are mutually exclusive; pick specific work items OR a source stage, not both |
Missing | 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 |
| Treating the deploy as synchronous | The promote deploy is async; capture the identifier and confirm completion before running |
| Production deploy fails on Apex coverage | Set |
| Deploy fails with conflict | A conflict slipped past validate; resolve the metadata conflict, then re-validate and retry |
| 问题 | 解决方法 |
|---|---|
| 验证失败 | 停止执行——请勿进行准备/合并/推广操作。报告非零状态码/错误信息;如果涉及元数据重叠,解决冲突后再重试 |
| 未设置默认组织 | 运行 |
| 传递工作项名称而非ID | 推广命令需要记录ID;通过 |
同时提供 | 二者互斥;选择特定工作项或源阶段,不可同时选择 |
缺少 | 所有推广命令(验证、准备、合并、推广、完成)均必填;从流水线配置中获取目标阶段ID |
| 合并推广时推广了错误的项 | 执行 |
| 将部署视为同步操作 | 推广部署是异步的;捕获标识符并确认完成后,再运行 |
| 生产部署因Apex覆盖率失败 | 对于包含Apex的生产阶段推广,设置 |
| 部署因冲突失败 | 冲突未被验证步骤检测到;解决元数据冲突后,重新验证并重试 |
Output Expectations
输出预期
Deliverables vary by operation:
- Validate: plus, when work items share metadata,
.result.success/.result.combineDetails. A non-zero exit (with.result.suggestions/.result.errorType) means the work item cannot be promoted to the target stage.result.errorDetails - 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 , , and CLI commands. Async deploy completion is NOT produced by the promote call — poll the returned identifier separately before completing.
sf devops work-itemsf devops promotesf devops promotion complete交付成果因操作而异:
- 验证:,当工作项共享元数据时还会返回
.result.success/.result.combineDetails。非零退出码(带有.result.suggestions/.result.errorType)表示工作项无法推广到目标阶段.result.errorDetails - 准备/合并:确认工作项已准备就绪(合并操作会返回父/子分组)
- 推广:异步部署标识符,以及推广部署已启动的确认信息
- 推广完成:确认工作项已在目标阶段中推进
输出来自、和 CLI命令。异步部署完成情况不会由推广调用返回——需单独轮询返回的标识符,然后再执行完成操作。
sf devops work-itemsf devops promotesf devops promotion completeCross-Skill Integration
跨技能集成
| When | Action |
|---|---|
| Work item must be created or moved to a promotable status first | Delegate to |
| 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 |
| 场景 | 操作 |
|---|---|
| 工作项必须先创建或移动到可推广状态 | 委托给 |
| 验证报告元数据重叠/冲突 | 解决元数据冲突后再重试 |
| 需轮询推广部署标识符以确认完成 | 单独轮询返回的标识符,然后运行 |
Reference File Index
参考文件索引
| File | When to read |
|---|---|
| When you need detailed CLI flag documentation, JSON output schemas, or error-handling patterns for validate/prepare/combine/promote/complete |
| When the user's request matches a common pattern (single work item promotion, combined promotion, whole-stage promotion, validate-first gate) |
| 文件 | 阅读时机 |
|---|---|
| 需要验证/准备/合并/推广/完成操作的详细CLI标志文档、JSON输出模式或错误处理模式时 |
| 用户请求匹配常见模式(单个工作项推广、合并推广、全阶段推广、先验证再执行)时 |