dx-devops-pipeline-manage

DevOps Center 流水线管理

管理 DevOps Center 中完整的流水线生命周期：从基于代码仓库创建流水线，到配置阶段和环境、关联项目，再到激活可供晋级的发布流水线。提供由无头 CLI 驱动的操作，以支持自主发布工作流。

范围

• 范围内：列出流水线、获取流水线详情、创建流水线（关联现有或新建的 Git 仓库）、添加/删除/重命名阶段、为阶段添加/删除 Salesforce 环境、关联/取消关联项目，以及激活/停用/重命名流水线
• 范围外：工作项生命周期、晋级/部署执行、冲突检测、独立创建项目（由单独的技能负责）

---

必需输入

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

• 操作类型：list、get、create、add-stage、delete-stage、rename-stage、add-environment、delete-environment、attach-project、detach-project、activate 或 deactivate
• 对于 get / 任何阶段或环境操作：流水线 ID（必需）——通过 sf devops pipeline list --json 获取
• 对于 create：流水线名称（必需）和 Git 仓库（--repo，必需）。不同场景的仓库标志参数有所不同：
  • 现有仓库（GitHub 或 Bitbucket）：仅使用 --repo <url>——不要传入 --repo-type/--create-repo
  • 新建 GitHub 仓库：--repo <name> --create-repo --repo-type github --repo-owner <org-or-user>
  • 新建 Bitbucket 仓库：--repo <name> --create-repo --repo-type bitbucket --bitbucket-workspace <workspace>（--bitbucket-project-key <key> 可选）
  • 所有场景下，描述（--description）均为可选
• 对于 add-stage：流水线 ID、新阶段名称，以及 --next-stage-id（新阶段之前的阶段）——通过 sf devops pipeline get 获取阶段 ID
• 对于 add-environment：流水线 ID、阶段 ID、环境名称，以及 --org-type（Production 或 Sandbox）
• 对于 attach/detach-project：流水线 ID 和项目 ID
• 对于 activate/deactivate/rename：流水线 ID

除非另有说明，默认使用：

• 输出格式：使用 --json 以供无头模式使用
• 目标组织：如果不使用默认组织，则使用 --target-org <alias>

如果用户的请求明确（例如，“在仓库 myorg/myrepo 上创建流水线”、“在 Production 前添加 UAT 阶段”、“激活流水线 0XB...”），请立即执行，无需提出不必要的问题。

---

工作流

所有操作均使用 sf devops pipeline 和 sf devops stage CLI 命令，并通过 --json 输出结构化数据。流水线 ID 和阶段 ID 是主要标识符——执行变更前，先通过 list 和 get 查询它们。

阶段 1 — 确定操作

1. 根据用户意图确定操作类型：
   • “list”、“show all pipelines” → list；“details of pipeline”、“show stages” → get
   • “create”、“set up”、“new pipeline” → create
   • “add stage”、“insert stage” → add-stage；“rename stage” → rename-stage；“remove/delete stage” → delete-stage
   • “connect environment”、“add org to stage” → add-environment；“remove environment” → delete-environment
   • “attach project”、“connect project” → attach-project；“detach project” → detach-project
   • “activate”、“turn on”；“deactivate”、“turn off”；“rename pipeline” → 生命周期更新

阶段 2 — 执行操作

2. 验证组织身份验证，然后再执行任何操作：

   sf org display --json
   

   • 如果未设置默认组织或身份验证已过期，请指导用户运行 sf org login web --set-default --alias <alias>
   • 运行 sf devops pipeline list --json，确认组织已启用 DevOps Center
   • 针对特定组织时，每条命令都要添加 --target-org <alias>

3. 检查流水线：

   sf devops pipeline list --json                              # all pipelines in the org
   sf devops pipeline get --pipeline-id <pipeline-id> --json   # one pipeline, with stages/repos/projects
   

   • list 会在 .result.pipelines[] 下返回 SObject 记录，字段首字母大写（.Id、.Name、.IsActive）——其中不包含阶段或关联项目
   • get 会在 .result 下返回单条流水线，字段使用驼峰命名（.id、.name、.stages[]、.connectedProjects[]）；每个阶段包含 .id、.name、.nextStageId、.branchName 和 .environment.{id,name}。阶段是一个链表——顺序由 nextStageId 定义，末尾阶段的 nextStageId 为 null。在执行任何阶段或环境操作前，使用 get 查找阶段 ID

4. 创建流水线——流水线必须关联到 Git 仓库。始终需要 --name 和 --repo；其余标志取决于仓库场景：

   # Existing repo (GitHub or Bitbucket) — pass the full repo URL, nothing else
   sf devops pipeline create --name "<pipeline-name>" --repo <repo-url> --json
   
   # New GitHub repo — requires --repo-owner
   sf devops pipeline create --name "<pipeline-name>" --repo <repo-name> \
     --create-repo --repo-type github --repo-owner <org-or-user> --json
   
   # New Bitbucket repo — requires --bitbucket-workspace (--bitbucket-project-key optional)
   sf devops pipeline create --name "<pipeline-name>" --repo <repo-name> \
     --create-repo --repo-type bitbucket --bitbucket-workspace <workspace> \
     --bitbucket-project-key <key> --json
   
   # Custom stage chain (any scenario) — repeat --stage in promotion order
   sf devops pipeline create --name "<pipeline-name>" --repo <repo-url> \
     --stage Dev --stage QA --stage Prod --json
   

   • 提供商特定的必需标志：GitHub 新仓库 → --repo-owner；Bitbucket 新仓库 → --bitbucket-workspace。省略提供商要求的标志会导致创建失败
   • 对于现有仓库，不要传入 --repo-type/--create-repo——只需通过 --repo 提供仓库 URL
   • 创建时自定义阶段：新流水线会初始化默认阶段链 集成 → UAT → 预发布 → 生产。若要初始化不同的阶段，请按晋级顺序为每个阶段重复使用一次 -s/--stage——例如 --stage Dev --stage QA --stage Prod。这样就不必事后添加或重命名阶段
   • 可在任何场景中选择添加 --description "<text>"
   • 保存返回的流水线 ID，以便后续执行阶段/环境/项目/激活操作
   • 幂等性：CLI 不会去重。创建前，运行 sf devops pipeline list --json，检查是否已有名称/仓库相同的流水线；如果找到，则返回已有流水线。检查后再创建的代码片段见 references/parsing-patterns.md

5. 配置阶段——相对于现有阶段添加一个阶段，然后将其关联到环境。执行多阶段操作前，阅读 references/cli-commands.md，了解所有标志的详细信息：

   # Insert an empty stage BEFORE an existing stage (get the next-stage-id from `pipeline get`)
   sf devops pipeline stage add --pipeline-id <id> --name "<stage-name>" --next-stage-id <stage-id> --json
   # Rename a stage
   sf devops pipeline stage update --pipeline-id <id> --stage-id <stage-id> --name "<new-name>" --json
   # Delete a stage (predecessor auto-relinks to successor)
   sf devops pipeline stage delete --pipeline-id <id> --stage-id <stage-id> --json
   

   • stage add 会在 --next-stage-id 指定的阶段之前插入一个空阶段（没有分支/环境）；需单独配置其环境
   • 通过在应后接的阶段之前插入每个新阶段，构建晋级链

6. 将环境关联到阶段——将 Salesforce 组织关联到一个阶段：

   # Validate the org-type against the fixed enum BEFORE calling the CLI
   bash scripts/validate-org-type.sh "<Production|Sandbox>"   # exits non-zero on an invalid value
   sf devops stage environment add --pipeline-id <id> --stage-id <stage-id> \
     --environment-name "<env-name>" --org-type <Production|Sandbox> --json
   # Remove an environment (pipeline must be inactive)
   sf devops stage environment delete --pipeline-id <id> --environment-id <env-id> --json
   

   • --org-type 必须严格为 Production 或 Sandbox——先运行 scripts/validate-org-type.sh <value>，仅在退出代码为 0 时继续
   • 无头模式注意事项：stage environment add 会触发 OAuth 浏览器流程。在无头/CI 运行中传入 --no-browser——CLI 会打印重定向 URL，供手动身份验证

7. 关联/取消关联项目——一个项目只能关联到一条流水线：

   sf devops pipeline project add --pipeline-id <id> --project-id <project-id> --json
   sf devops pipeline project delete --pipeline-id <id> --project-id <project-id> --json
   

   • 如果用户提供的是项目名称而非 ID，请通过 sf devops project list --json 查找项目（参见 references/parsing-patterns.md）

8. 激活/停用/重命名流水线：

   # Before activating, confirm the deterministic ≥1-stage prerequisite
   bash scripts/check-activation-ready.sh <id> [target-org]   # exits non-zero if stage-less
   sf devops pipeline update --pipeline-id <id> --activate --json             # activate
   sf devops pipeline update --pipeline-id <id> --deactivate --json           # deactivate
   sf devops pipeline update --pipeline-id <id> --name "<new-name>" --json    # rename
   

   • 执行 --activate 前，运行 scripts/check-activation-ready.sh <id>，仅在退出代码为 0 时继续——如果流水线没有阶段，该脚本会返回可操作的提示
   • 流水线激活且变更已通过其晋级后，便无法再修改阶段——请在激活前完成阶段/环境配置
   • --activate 和 --deactivate 不能同时使用；--deactivate 和 --name 可以在同一条命令中组合使用

第 3 阶段 — 验证并报告

9. 验证操作是否成功 — 使用 scripts/verify-operation.sh，该脚本会确定性地检查 JSON 状态和操作后的字段，并在不匹配时以非零状态退出，同时提供可执行的提示：

   # Assert a captured command's JSON status is 0 (pipe the CLI output in)
   sf devops pipeline update --pipeline-id <id> --activate --json | bash scripts/verify-operation.sh status -
   # Assert post-state after activate / stage / project ops
   bash scripts/verify-operation.sh active      <id> true         [target-org]   # isActive == true
   bash scripts/verify-operation.sh has-stage   <id> "<stage>"    [target-org]   # stage present in chain
   bash scripts/verify-operation.sh has-project <id> "<project>"  [target-org]   # project connected
   

   • 创建：通过 .Name 确认流水线出现在 sf devops pipeline list --json 中，并记录其 .Id
   • 阶段 / 环境 / 项目变更：使用上述 has-stage / has-project 模式验证（它们会读取 sf devops pipeline get 并检查 .result.stages[] / .result.connectedProjects[]）
   • 激活：使用 active <id> true 模式验证

10. 报告结果：

    • 列表：逐个报告流水线名称、ID 和激活状态（不包含阶段——查看阶段应使用 get）
    • 获取：报告流水线名称、ID、激活状态、阶段链（按 nextStageId 排序，包含每个阶段的名称 → 环境 → 分支）以及关联项目
    • 创建：报告流水线 ID、名称和关联的仓库（若幂等匹配，则报告“返回了现有流水线”）
    • 阶段 / 环境 / 项目操作：报告操作后的阶段链及每个阶段的环境，并按晋升顺序排列
    • 生命周期：报告新的激活状态和／或名称

验证清单（报告成功前的门槛）

确认你执行的操作对应的项目。所有适用的项目均满足前，不要报告成功：

• 每条 sf devops 命令都使用了 --json，并返回 status: 0（scripts/verify-operation.sh status -）
• 创建：新流水线按名称出现在 sf devops pipeline list --json 中；对于新仓库，还须提供提供商专属标志（GitHub 使用 --repo-owner，Bitbucket 使用 --bitbucket-workspace）
• 添加阶段 / 添加环境：该阶段存在于链中，且 --org-type 通过了 scripts/validate-org-type.sh（scripts/verify-operation.sh has-stage ...）
• 关联项目：该项目显示在 .result.connectedProjects[] 中（scripts/verify-operation.sh has-project ...）
• 激活：事先通过了 scripts/check-activation-ready.sh，且 .result.isActive 现在为 true（scripts/verify-operation.sh active <id> true）
• 删除环境：删除前，该流水线处于未激活状态

---

规则 / 限制

限制	原因
所有 sf devops 命令都必须使用 --json 标志	无头模式下需要结构化输出；人类可读的输出不可靠，无法用于解析
创建管道时必须有 Git 仓库	sf devops pipeline create 需要 --name 和 --repo；对于现有仓库，只需传入 URL；对于新仓库，需添加 --create-repo 和 --repo-type
创建新仓库需要特定提供商的标志	GitHub 需要 --repo-owner；Bitbucket 需要 --bitbucket-workspace（--bitbucket-project-key 可选）。使用错误提供商的标志会导致命令失败
获取、更新以及所有阶段／环境／项目操作都需要管道 ID	这些命令仅通过 --pipeline-id 标识管道；可通过 sf devops pipeline list 获取
阶段 ID 来自 pipeline get	stage add（--next-stage-id）、stage update／delete（--stage-id）以及 stage environment add（--stage-id）都需要阶段 ID
stage add 会在 --next-stage-id 指定的阶段之前插入一个空阶段	阶段在添加环境之前不包含任何环境；通过指定后续阶段来构建阶段链
--org-type 必须严格为 Production 或 Sandbox	此标志是固定枚举值；其他值会导致失败
激活前，管道必须至少有 1 个阶段	sf devops pipeline update --activate 会拒绝不含阶段的管道
激活并提升变更后，不要修改阶段	变更通过激活的管道完成提升后，DevOps Center 会锁定阶段结构
删除环境需要管道处于非激活状态	只有在管道处于非激活状态时，stage environment delete 才会成功
一个项目只能关联到一个管道	如果项目已关联到其他管道，pipeline project add 会失败；请先解除关联
通过先检查再创建来实现幂等创建	CLI 不会去重；请先列出现有管道并返回匹配项，而不是报错
无头模式下优先使用 --no-browser	stage environment add 会打开 OAuth 浏览器流程；--no-browser 会打印重定向 URL，供 CI 使用

---

注意事项

问题	解决方法
未设置默认组织	先运行 sf org display --json；如果失败，请指示用户运行 sf org login web --set-default
创建失败 — 缺少仓库	--repo 为必填项；传入现有仓库 URL，或为新仓库传入 --create-repo + --repo-type
创建新仓库失败 — 缺少提供商标志	GitHub 新仓库需要 --repo-owner；Bitbucket 新仓库需要 --bitbucket-workspace。不要混用不同提供商的标志（将 --repo-owner 与 bitbucket 搭配，或将 --bitbucket-workspace 与 github 搭配）
stage add 失败 — 缺少 next-stage-id	--next-stage-id 为必填项；运行 sf devops pipeline get --pipeline-id <id> --json 查找阶段 ID，并选择新阶段应插入其前面的阶段
在 CI 中添加环境时卡住	OAuth 浏览器流程会阻塞无头模式运行；添加 --no-browser，并通过打印的重定向 URL 完成身份验证
激活请求被拒绝	管道至少需要一个阶段；在使用 --activate 之前，添加一个阶段（及其环境）
无法修改阶段	管道已激活并提升了变更；阶段结构已锁定 — 必须在激活前完成配置
删除环境失败	管道处于激活状态；删除环境前，使用 pipeline update --deactivate 停用管道
项目已关联	一个项目只能关联到一个管道；请先通过 pipeline project delete 将其从另一个管道解除关联
未找到管道／阶段／项目	ID 无效；运行 sf devops pipeline list --json、sf devops pipeline get --json 或 sf devops project list --json 查找有效 ID

---

输出预期

交付内容因操作而异：

• List：包含 ID、名称和启用状态的流水线（列表视图中不包含阶段／项目）
• Get：包含 ID、名称、启用状态、阶段链（每个阶段都包含环境和分支，并按 nextStageId 排序）以及关联项目的流水线
• Create：流水线 ID、名称和关联的代码库（或幂等匹配时已存在的流水线）
• Stage op：更新后的有序阶段链
• Environment op：包含已绑定环境（名称、组织类型）的阶段
• Project op：关联／取消关联的确认信息
• Lifecycle：新的启用状态和／或流水线名称

输出源自 sf devops pipeline 和 sf devops stage CLI 命令。

---

跨技能集成

委派给	适用场景
dx-devops-work-item-manage	用户希望在流水线启用后创建或推进工作项时

如果找不到用户希望关联的项目，请使用 sf devops project list --json（参见 references/parsing-patterns.md）解析或列出现有项目，而不要委派——项目创建不属于此技能的范围。

---

参考文件索引

文件	何时阅读
references/cli-commands.md	需要详细了解每个 sf devops pipeline／sf devops stage 命令的 CLI 标志文档和 JSON 输出架构时
references/parsing-patterns.md	需要用于解析 JSON 的 jq 代码片段（阶段链、流水线／项目 ID 解析）、错误处理参考、创建前检查的幂等模式或身份验证要求时
examples/common-workflows.md	用户请求符合常见模式（端到端流水线设置、插入阶段、绑定环境、关联项目、启用）时
scripts/validate-org-type.sh	在运行 stage environment add 前执行，以根据 Production／Sandbox 枚举验证 --org-type
scripts/check-activation-ready.sh	在运行 pipeline update --activate 前执行，以确认流水线至少有 1 个阶段
scripts/verify-operation.sh	在第 3 阶段执行，以验证命令的 JSON 状态和操作后的字段（status／active／has-stage／has-project）