dx-devops-pipeline-manage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DevOps Center Pipeline Management

DevOps Center 流水线管理

Manages the complete pipeline lifecycle in DevOps Center — from creation against a repository, through stage and environment configuration and project attachment, to activation of a ready-to-promote release pipeline. Provides headless CLI-driven operations for autonomous release workflows.

管理DevOps Center中流水线的完整生命周期——从关联仓库创建流水线，到阶段与环境配置、项目附加，再到激活可用于晋升的发布流水线。提供基于无头CLI的操作，支持自主发布工作流。

Scope

适用范围

In scope: List pipelines, get pipeline details, create a pipeline (linked to an existing or new Git repo), add/delete/rename stages, add/delete Salesforce environments on stages, attach/detach projects, and activate/deactivate/rename the pipeline
Out of scope: Work-item lifecycle, promotion/deployment execution, conflict detection, standalone project creation (separate skills)

包含的操作：列出流水线、获取流水线详情、创建流水线（关联现有或新Git仓库）、添加/删除/重命名阶段、在阶段中添加/删除Salesforce环境、附加/分离项目、激活/停用/重命名流水线
不包含的操作：工作项生命周期、晋升/部署执行、冲突检测、独立项目创建（对应单独的技能）

Required Inputs

必要输入

Gather or infer before proceeding:

Operation type: list, get, create, add-stage, delete-stage, rename-stage, add-environment, delete-environment, attach-project, detach-project, activate, or deactivate
For get / any stage or environment op: pipeline ID (required) — obtain via
```
sf devops pipeline list --json
```

For create: pipeline name (required) and a Git repo (

--repo

, required). Repo flags differ by scenario:

Existing repo (GitHub or Bitbucket): only
```
--repo <url>
```
— do not pass
```
--repo-type
```
/
```
--create-repo
```

New GitHub repo:

--repo <name> --create-repo --repo-type github --repo-owner <org-or-user>

New Bitbucket repo:

--repo <name> --create-repo --repo-type bitbucket --bitbucket-workspace <workspace>

(

--bitbucket-project-key <key>

optional)

Description (
```
--description
```
) optional in all cases

For add-stage: pipeline ID, new stage name, and
```
--next-stage-id
```
(the stage the new one precedes) — get stage IDs via
```
sf devops pipeline get
```
For add-environment: pipeline ID, stage ID, environment name, and
```
--org-type
```
(Production or Sandbox)
For attach/detach-project: pipeline ID and project ID
For activate/deactivate/rename: pipeline ID

Defaults unless specified:

Output format:
```
--json
```
for headless consumption
Target org: use
```
--target-org <alias>
```
if not relying on the default org

If the user gives a clear request ("create a pipeline on repo myorg/myrepo", "add a UAT stage before Production", "activate pipeline 0XB..."), proceed immediately without unnecessary questions.

执行前需收集或推断以下信息：

操作类型：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..."），请直接执行，无需额外询问。

Workflow

工作流

All operations use

sf devops pipeline

and

sf devops stage

CLI commands with

--json

output for structured consumption. Pipeline IDs and stage IDs are the primary identifiers — resolve them via

list

and

get

before mutating.

所有操作均使用

sf devops pipeline

和

sf devops stage

CLI命令，并以

--json

格式输出，便于结构化消费。流水线ID和阶段ID是主要标识符——在修改前需通过

list

和

get

命令获取。

Phase 1 — Identify Operation

阶段1 — 确定操作类型

Determine the operation type from user intent:
- "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" → lifecycle update

根据用户意图确定操作类型：
- "列出"、"显示所有流水线" → list；"流水线详情"、"显示阶段" → get
- "创建"、"设置"、"新流水线" → create
- "添加阶段"、"插入阶段" → add-stage；"重命名阶段" → rename-stage；"移除/删除阶段" → delete-stage
- "连接环境"、"为阶段添加组织" → add-environment；"移除环境" → delete-environment
- "附加项目"、"连接项目" → attach-project；"分离项目" → detach-project
- "激活"、"开启"；"停用"、"关闭"；"重命名流水线" → 生命周期更新

Phase 2 — Execute Operation

阶段2 — 执行操作

Verify org authentication before any operation:
bash
```
sf org display --json
```
- If no default org is set or auth has expired, instruct the user to run
```
sf org login web --set-default --alias <alias>
```
- Confirm the org has DevOps Center enabled by running
```
sf devops pipeline list --json
```
- Add
```
--target-org <alias>
```
  to every command when targeting a specific org

Inspect pipelines:

bash

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
```
returns SObject records under
```
.result.pipelines[]
```
with capitalized fields (
```
.Id
```
,
```
.Name
```
,
```
.IsActive
```
) — it does not include stages or connected projects
```
get
```
returns a single pipeline under
```
.result
```
with camelCase fields (
```
.id
```
,
```
.name
```
,
```
.stages[]
```
,
```
.connectedProjects[]
```
); each stage has
```
.id
```
,
```
.name
```
,
```
.nextStageId
```
,
```
.branchName
```
, and
```
.environment.{id,name}
```
. Stages are a linked list — order is defined by
```
nextStageId
```
, and the terminal stage has
```
nextStageId: null
```
. Use
```
get
```
to discover stage IDs before any stage or environment operation

Create a pipeline — the pipeline must be linked to a Git repository.

--name

and

--repo

are always required; the remaining flags depend on the repo scenario:

bash

# 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

Provider-specific required flags: GitHub new repo →
```
--repo-owner
```
; Bitbucket new repo →
```
--bitbucket-workspace
```
. Omitting the provider's required flag fails the create
Do not pass
```
--repo-type
```
/
```
--create-repo
```
for an existing repo — supply only the repo URL via
```
--repo
```
Custom stages at create time: a new pipeline seeds the default stage chain Integration → UAT → Staging → Production. To seed different stages, repeat
```
-s/--stage
```
once per stage in promotion order — e.g.
```
--stage Dev --stage QA --stage Prod
```
. This avoids adding/renaming stages afterward
Add
```
--description "<text>"
```
optionally in any scenario
Capture the returned pipeline ID for subsequent stage/environment/project/activation steps
Idempotency: the CLI does not dedupe. Before creating, run
```
sf devops pipeline list --json
```
and check for a pipeline with the same name/repo; return the existing one if found. See
```
references/parsing-patterns.md
```
for the check-before-create snippet

Configure stages — a stage is added relative to an existing stage, then bound to an environment. Read
references/cli-commands.md
for full flag details before multi-stage work:

bash

# 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
```
inserts an empty stage (no branch/environment) before
```
--next-stage-id
```
; configure its environment separately
Build the promotion chain by inserting each new stage before the stage that should follow it

Bind environments to stages — attach a Salesforce org to a stage:

bash

# 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

must be exactly

Production

Sandbox

— run

scripts/validate-org-type.sh <value>

first and only proceed on exit 0

Headless caveat:
```
stage environment add
```
triggers an OAuth browser flow. In headless/CI runs pass
```
--no-browser
```
— the CLI prints a redirect URL for manual authentication

Attach / detach a project — a project can be attached to only one pipeline:

bash

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

If the user names a project instead of providing its ID, resolve it via
```
sf devops project list --json
```
(see
```
references/parsing-patterns.md
```
)

Activate / deactivate / rename the pipeline:

bash

# 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

Before
```
--activate
```
, run
```
scripts/check-activation-ready.sh <id>
```
and only proceed on exit 0 — it fails with an actionable message when the pipeline has no stages
Stages cannot be modified after the pipeline is activated and changes are promoted through it — finish stage/environment configuration before activating
```
--activate
```
and
```
--deactivate
```
are mutually exclusive;
```
--deactivate
```
and
```
--name
```
may be combined in one command

执行任何操作前验证组织身份认证：
bash
```
sf org display --json
```
- 若未设置默认组织或认证已过期，指导用户运行
```
sf org login web --set-default --alias <alias>
```
- 通过运行
```
sf devops pipeline list --json
```
  确认该组织已启用DevOps Center
- 当目标为特定组织时，在所有命令中添加
```
--target-org <alias>
```

查看流水线信息：

bash

sf devops pipeline list --json                              # 组织中的所有流水线
sf devops pipeline get --pipeline-id <pipeline-id> --json   # 单个流水线，包含阶段/仓库/项目信息

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

创建流水线——流水线必须关联Git仓库。

--name

和

--repo

始终为必填项；其余参数取决于仓库场景：

bash

# 现有仓库（GitHub或Bitbucket）——传递完整仓库URL即可
sf devops pipeline create --name "<pipeline-name>" --repo <repo-url> --json

# 新GitHub仓库——需要--repo-owner
sf devops pipeline create --name "<pipeline-name>" --repo <repo-name> \
  --create-repo --repo-type github --repo-owner <org-or-user> --json

# 新Bitbucket仓库——需要--bitbucket-workspace（--bitbucket-project-key可选）
sf devops pipeline create --name "<pipeline-name>" --repo <repo-name> \
  --create-repo --repo-type bitbucket --bitbucket-workspace <workspace> \
  --bitbucket-project-key <key> --json

# 自定义阶段链（任何场景）——按晋升顺序重复--stage参数
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即可
创建时自定义阶段：新流水线默认生成阶段链为「Integration → UAT → Staging → Production」。如需生成不同阶段，按晋升顺序为每个阶段重复
```
-s/--stage
```
参数——例如
```
--stage Dev --stage QA --stage Prod
```
。这样可避免后续添加/重命名阶段
所有场景中可选择性添加
```
--description "<text>"
```
记录返回的流水线ID，用于后续的阶段/环境/项目/激活操作
幂等性：CLI不会自动去重。创建前运行
```
sf devops pipeline list --json
```
，检查是否存在同名/同仓库的流水线；若存在则返回现有流水线。幂等性检查代码片段可参考
```
references/parsing-patterns.md
```

配置阶段——阶段需相对于现有阶段添加，然后绑定到环境。**执行多阶段操作前，请阅读

references/cli-commands.md

**获取完整参数详情：

bash

# 在现有阶段之前插入一个空阶段（从`pipeline get`获取next-stage-id）
sf devops pipeline stage add --pipeline-id <id> --name "<stage-name>" --next-stage-id <stage-id> --json
# 重命名阶段
sf devops pipeline stage update --pipeline-id <id> --stage-id <stage-id> --name "<new-name>" --json
# 删除阶段（前驱阶段会自动链接到后继阶段）
sf devops pipeline stage delete --pipeline-id <id> --stage-id <stage-id> --json

```
stage add
```
会在
```
--next-stage-id
```
指定的阶段之前插入一个空阶段（无分支/环境）；需单独配置其环境
通过在后续阶段之前插入每个新阶段来构建晋升链

将环境绑定到阶段——将Salesforce组织附加到阶段：

bash

# 在调用CLI前，验证org-type是否符合固定枚举值
bash scripts/validate-org-type.sh "<Production|Sandbox>"   # 若值无效则返回非零退出码
sf devops stage environment add --pipeline-id <id> --stage-id <stage-id> \
  --environment-name "<env-name>" --org-type <Production|Sandbox> --json
# 移除环境（流水线必须处于停用状态）
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供手动认证

附加/分离项目——一个项目只能附加到一条流水线：

bash

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
```
）

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

bash

# 激活前，确认流水线至少包含一个阶段的前置条件
bash scripts/check-activation-ready.sh <id> [target-org]   # 若无阶段则返回非零退出码
sf devops pipeline update --pipeline-id <id> --activate --json             # 激活
sf devops pipeline update --pipeline-id <id> --deactivate --json           # 停用
sf devops pipeline update --pipeline-id <id> --name "<new-name>" --json    # 重命名

执行
```
--activate
```
前，运行
```
scripts/check-activation-ready.sh <id>
```
，仅当退出码为0时才继续执行——当流水线无阶段时，该脚本会返回可操作的错误信息
流水线激活且已完成晋升后，无法修改阶段——请在激活前完成阶段/环境配置
```
--activate
```
和
```
--deactivate
```
互斥；
```
--deactivate
```
和
```
--name
```
可在同一命令中组合使用

Phase 3 — Verify and Report

阶段3 — 验证并报告结果

Verify operation success — use

scripts/verify-operation.sh

, which performs the deterministic JSON-status and post-state field checks and exits non-zero with an actionable message on mismatch:

bash

# 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

Create: confirm the pipeline appears in
```
sf devops pipeline list --json
```
by
```
.Name
```
and capture its
```
.Id
```
Stage / environment / project changes: verify with the
```
has-stage
```
/
```
has-project
```
modes above (they read
```
sf devops pipeline get
```
and check
```
.result.stages[]
```
/
```
.result.connectedProjects[]
```
)
Activate: verify with the
```
active <id> true
```
mode

Report results:
- List: pipeline name, ID, and active state per pipeline (no stages — that's what
```
get
```
  is for)
- Get: pipeline name, ID, active state, stage chain (each stage's name → environment → branch, ordered via
```
nextStageId
```
  ), connected projects
- Create: pipeline ID, name, and linked repo (or "existing pipeline returned" on idempotent match)
- Stage / environment / project op: the resulting stage chain with each stage's environment, in promotion order
- Lifecycle: the new active state and/or name

验证操作成功——使用

scripts/verify-operation.sh

，该脚本会检查JSON状态和操作后的状态字段，若不匹配则返回非零退出码并给出可操作信息：

bash

# 断言捕获的命令JSON状态为0（将CLI输出传入）
sf devops pipeline update --pipeline-id <id> --activate --json | bash scripts/verify-operation.sh status -
# 断言激活/阶段/项目操作后的状态
bash scripts/verify-operation.sh active      <id> true         [target-org]   # isActive == true
bash scripts/verify-operation.sh has-stage   <id> "<stage>"    [target-org]   # 阶段存在于链中
bash scripts/verify-operation.sh has-project <id> "<project>"  [target-org]   # 项目已连接

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

报告结果：
- List操作：每条流水线的名称、ID和激活状态（不包含阶段——阶段信息需通过
```
get
```
  获取）
- Get操作：流水线名称、ID、激活状态、阶段链（每个阶段的名称→环境→分支，按
```
nextStageId
```
  排序）、关联项目
- Create操作：流水线ID、名称和关联仓库（若为幂等匹配则返回"返回现有流水线"）
- 阶段/环境/项目操作：更新后的阶段链，包含每个阶段的环境，按晋升顺序排列
- 生命周期操作：新的激活状态和/或流水线名称

Verification Checklist (gate before reporting success)

验证清单（报告成功前需确认）

Confirm the items for the operation you performed. Do not report success until every applicable box holds:

Every

sf devops

command was run with

--json

and returned

status: 0

(

scripts/verify-operation.sh status -

)

Create: the new pipeline appears in
```
sf devops pipeline list --json
```
by name, and (for a new repo) the provider-specific flags were supplied (
```
--repo-owner
```
for GitHub,
```
--bitbucket-workspace
```
for Bitbucket)

Add-stage / add-environment: the stage exists in the chain and

--org-type

passed

scripts/validate-org-type.sh

(

scripts/verify-operation.sh has-stage ...

)

Attach-project: the project shows in

.result.connectedProjects[]

(

scripts/verify-operation.sh has-project ...

)

Activate:

scripts/check-activation-ready.sh

passed beforehand and

.result.isActive

is now

true

(

scripts/verify-operation.sh active <id> true

)

Delete-environment: the pipeline was inactive before the delete

确认所执行操作对应的所有项均已完成。所有适用项均满足后，方可报告成功：

所有

sf devops

命令均使用

--json

参数，且返回

status: 0

（通过

scripts/verify-operation.sh status -

验证）

Create操作：新流水线通过名称出现在
```
sf devops pipeline list --json
```
中，且（针对新仓库）已提供特定提供商的必填参数（GitHub的
```
--repo-owner
```
，Bitbucket的
```
--bitbucket-workspace
```
）
Add-stage / add-environment操作：阶段存在于链中，且
```
--org-type
```
通过
```
scripts/validate-org-type.sh
```
验证（通过
```
scripts/verify-operation.sh has-stage ...
```
验证）

Attach-project操作：项目显示在

.result.connectedProjects[]

中（通过

scripts/verify-operation.sh has-project ...

验证）

Activate操作：执行前

scripts/check-activation-ready.sh

已通过，且

.result.isActive

现在为

true

（通过

scripts/verify-operation.sh active <id> true

验证）

Delete-environment操作：删除前流水线处于停用状态

Rules / Constraints

规则/约束

Constraint	Rationale
All sf devops commands must use `--json` flag	Structured output is required for headless consumption; human-readable output is unreliable for parsing
A pipeline requires a Git repo at create time	`sf devops pipeline create` requires `--name` and `--repo` ; for an existing repo pass only the URL, for a new repo add `--create-repo` and `--repo-type`
New-repo create needs provider-specific flags	GitHub requires `--repo-owner` ; Bitbucket requires `--bitbucket-workspace` ( `--bitbucket-project-key` optional). The wrong provider's flags fail the command
Pipeline ID required for get, update, and all stage/environment/project ops	These commands identify the pipeline only by `--pipeline-id` ; obtain it via `sf devops pipeline list`
Stage IDs come from `pipeline get`	`stage add` ( `--next-stage-id` ), `stage update` / `delete` ( `--stage-id` ), and `stage environment add` ( `--stage-id` ) all need stage IDs
`stage add` inserts an empty stage before `--next-stage-id`	Stages carry no environment until one is added; build the chain by anchoring to the following stage
`--org-type` must be exactly `Production` or `Sandbox`	The flag is a fixed enum; other values fail
Pipeline must have ≥1 stage before activation	`sf devops pipeline update --activate` rejects a stage-less pipeline
Do not modify stages after activate + promote	DevOps Center locks stage structure once changes have been promoted through an active pipeline
Environment delete requires an inactive pipeline	`stage environment delete` only succeeds while the pipeline is inactive
A project attaches to only one pipeline	`pipeline project add` fails if the project is already attached elsewhere; detach first
Idempotent create via check-before-create	The CLI does not dedupe; list existing pipelines and return the match instead of erroring
Prefer `--no-browser` in headless runs	`stage environment add` opens an OAuth browser flow; `--no-browser` prints a redirect URL for CI

约束	理由
所有sf devops命令必须使用 `--json` 参数	结构化输出是无头场景消费的必要条件；人类可读输出解析不可靠
创建流水线时必须关联Git仓库	`sf devops pipeline create` 需要 `--name` 和 `--repo` ；针对现有仓库仅需传递URL，针对新仓库需添加 `--create-repo` 和 `--repo-type`
创建新仓库时需要特定提供商的参数	GitHub需要 `--repo-owner` ；Bitbucket需要 `--bitbucket-workspace` （ `--bitbucket-project-key` 可选）。使用错误提供商的参数会导致命令失败
get、update以及所有阶段/环境/项目操作需要流水线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`	该参数为固定枚举值；其他值会导致命令失败
激活流水线前必须至少包含一个阶段	`sf devops pipeline update --activate` 会拒绝无阶段的流水线
激活并完成晋升后请勿修改阶段	DevOps Center会在激活流水线并完成晋升后锁定阶段结构
删除环境需要流水线处于停用状态	`stage environment delete` 仅在流水线停用状态下成功
一个项目只能附加到一条流水线	若项目已附加到其他流水线， `pipeline project add` 会失败；需先分离
通过先检查再创建实现幂等性	CLI不会自动去重；列出现有流水线并返回匹配项，而非报错
无头运行中优先使用 `--no-browser`	`stage environment add` 会打开OAuth浏览器流程； `--no-browser` 会打印重定向URL供CI场景使用

Gotchas

常见问题

Issue	Resolution
No default org set	Run `sf org display --json` first; if it fails, instruct user to run `sf org login web --set-default`
Create fails — missing repo	`--repo` is required; pass an existing repo URL, or `--create-repo` + `--repo-type` for a new repo
New-repo create fails — missing provider flag	GitHub new repo needs `--repo-owner` ; Bitbucket new repo needs `--bitbucket-workspace` . Don't mix providers' flags ( `--repo-owner` with `bitbucket` , or `--bitbucket-workspace` with `github` )
`stage add` fails — no next-stage-id	`--next-stage-id` is required; run `sf devops pipeline get --pipeline-id <id> --json` to find the stage IDs and pick the one the new stage should precede
Environment add hangs in CI	The OAuth browser flow blocks headless runs; add `--no-browser` and complete auth via the printed redirect URL
Activation rejected	The pipeline needs at least one stage; add a stage (and its environment) before `--activate`
Cannot modify stages	The pipeline is active and has promoted changes; stage structure is locked — configuration must complete before activation
Environment delete fails	The pipeline is active; deactivate with `pipeline update --deactivate` before deleting the environment
Project already attached	A project attaches to only one pipeline; detach from the other pipeline first via `pipeline project delete`
Pipeline / stage / project not found	The ID is invalid; run `sf devops pipeline list --json` , `sf devops pipeline get --json` , or `sf devops project list --json` to find valid IDs

问题	解决方案
未设置默认组织	先运行 `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，并选择新阶段应排在其之前的阶段ID
CI环境中添加环境操作挂起	OAuth浏览器流程会阻塞无头运行；添加 `--no-browser` 并通过打印的重定向URL完成认证
激活被拒绝	流水线需要至少一个阶段；激活前添加阶段（及其环境）
无法修改阶段	流水线已激活且已完成晋升；阶段结构已锁定——需在激活前完成配置
删除环境失败	流水线处于激活状态；先通过 `pipeline update --deactivate` 停用流水线，再删除环境
项目已附加	一个项目只能附加到一条流水线；先通过 `pipeline project delete` 从其他流水线分离
流水线/阶段/项目未找到	ID无效；运行 `sf devops pipeline list --json` 、 `sf devops pipeline get --json` 或 `sf devops project list --json` 获取有效ID

Output Expectations

输出预期

Deliverables vary by operation:

List: pipelines with ID, name, and active state (no stages/projects in the list view)
Get: a pipeline with ID, name, active state, its stage chain (each with environment and branch, ordered via
```
nextStageId
```
), and connected projects
Create: pipeline ID, name, and linked repository (or the pre-existing pipeline on idempotent match)
Stage op: the updated ordered stage chain
Environment op: the stage with its bound environment (name, org-type)
Project op: confirmation of attach/detach
Lifecycle: the new active state and/or pipeline name

Outputs are derived from

sf devops pipeline

and

sf devops stage

CLI commands.

交付内容因操作而异：

List操作：流水线的ID、名称和激活状态（列表视图中不包含阶段/项目）
Get操作：流水线的ID、名称、激活状态、阶段链（每个阶段包含环境和分支，按
```
nextStageId
```
排序）以及关联项目
Create操作：流水线ID、名称和关联仓库（若为幂等匹配则返回现有流水线）
阶段操作：更新后的有序阶段链
环境操作：绑定了环境的阶段（名称、org-type）
项目操作：附加/分离的确认信息
生命周期操作：新的激活状态和/或流水线名称

输出内容均来自

sf devops pipeline

和

sf devops stage

CLI命令。

Cross-Skill Integration

跨技能集成

Delegate to	When
`dx-devops-work-item-manage`	The user wants to create or advance work items once the pipeline is active

If a project the user wants to attach can't be found, resolve or list existing projects with

sf devops project list --json

(see

references/parsing-patterns.md

) rather than delegating — project creation is out of scope for this skill.

委托至	场景
`dx-devops-work-item-manage`	用户想要在流水线激活后创建或推进工作项

如果用户想要附加的项目无法找到，可通过

sf devops project list --json

解析或列出现有项目（参考

references/parsing-patterns.md

），而非委托——项目创建不属于此技能的范围。

Reference File Index

参考文件索引

File	When to read
`references/cli-commands.md`	When you need detailed CLI flag documentation and JSON output schemas for each `sf devops pipeline` / `sf devops stage` command
`references/parsing-patterns.md`	When you need jq snippets to parse the JSON (stage chains, pipeline/project ID resolution), error-handling reference, the check-before-create idempotent pattern, or auth requirements
`examples/common-workflows.md`	When the user's request matches a common pattern (end-to-end pipeline setup, inserting a stage, binding an environment, attaching a project, activation)
`scripts/validate-org-type.sh`	Run before `stage environment add` to validate `--org-type` against the `Production` / `Sandbox` enum
`scripts/check-activation-ready.sh`	Run before `pipeline update --activate` to confirm the pipeline has ≥1 stage
`scripts/verify-operation.sh`	Run in Phase 3 to assert a command's JSON status and post-state fields ( `status` / `active` / `has-stage` / `has-project` )

文件	阅读场景
`references/cli-commands.md`	需要每个 `sf devops pipeline` / `sf devops stage` 命令的详细CLI参数文档和JSON输出 schema时
`references/parsing-patterns.md`	需要jq代码片段解析JSON（阶段链、流水线/项目ID解析）、错误处理参考、先检查再创建的幂等模式或认证要求时
`examples/common-workflows.md`	用户请求匹配常见模式（端到端流水线设置、插入阶段、绑定环境、附加项目、激活）时
`scripts/validate-org-type.sh`	在 `stage environment add` 前运行，验证 `--org-type` 是否符合 `Production` / `Sandbox` 枚举值时
`scripts/check-activation-ready.sh`	在 `pipeline update --activate` 前运行，确认流水线至少包含一个阶段时
`scripts/verify-operation.sh`	在阶段3中使用，断言命令的JSON状态和操作后的状态字段（ `status` / `active` / `has-stage` / `has-project` ）时