kris/afv-library
1
0
Fork 0
mirror of https://github.com/forcedotcom/afv-library.git synced 2026-08-10 01:32:48 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
39c8ccf0f8
afv-library/skills/dx-devops-pipeline-manage/SKILL.md

19 KiB
Raw Blame History

name description metadata
dx-devops-pipeline-manage Use this skill to manage the full lifecycle of a DevOps Center pipeline — list all pipelines, get a single pipeline's details, create a new pipeline linked to a Git repository, add or remove stages, rename a stage, add or remove Salesforce environments on stages, attach or detach projects, and activate or deactivate the pipeline. Invoke when the user wants to set up a release pipeline, wire promotion stages across integration, UAT, staging, and production orgs, connect environments to stages, attach a project, or activate a continuous delivery pipeline. Uses sf devops pipeline and sf devops stage commands with --json output. DO NOT TRIGGER for work-item lifecycle, promotion or deployment execution, conflict detection, or standalone project creation (separate skills).
version minApiVersion relatedSkills accessCheck cliTools
1.0 58.0
dx-devops-work-item-manage
type value
orgPref ALMDevopsCorePref
type value
userPerm UserHasDevOpsCore
tool semver
jq
>=1.6
tool semver
sf
>=2.0.0

DevOps Center Pipeline Management

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.

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)

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.

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.

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

Phase 2 — Execute Operation

  1. Verify org authentication before any operation:

    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

  2. Inspect pipelines:

    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

  3. 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:

    # 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

  4. 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:

    # 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

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

    # 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 or 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

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

    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)

  7. Activate / deactivate / rename the pipeline:

    # 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

Phase 3 — Verify and Report

  1. 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:

    # 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

  2. 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

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

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

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

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.

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.

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)