afv-library/skills/dx-devops-pipeline-manage/examples/common-workflows.md

Common Pipeline Management Workflows

Real-world examples of typical pipeline operations in DevOps Center autonomous release scenarios. All commands use --json; add --target-org <alias> when not relying on the default org.

---

Workflow 1: End-to-End Pipeline Setup — Create, Stage, Bind Environments, Activate

User request: "Set up a release pipeline on repo myorg/myrepo with Integration → UAT → Production and activate it"

Steps:

1. Create the pipeline against the existing repo, then resolve its ID from the list:

   sf devops pipeline create \
     --name "Release Pipeline" \
     --repo https://github.com/myorg/myrepo \
     --json
   PIPELINE_ID=$(sf devops pipeline list --json | \
     jq -r '.result.pipelines[] | select(.Name == "Release Pipeline") | .Id' | head -n1)
   

2. Inspect the initial stages (a new pipeline always starts with at least one seeded stage):

   sf devops pipeline get --pipeline-id "$PIPELINE_ID" --json | \
     jq -r '.result.stages[] | "\(.name) (\(.id)) -> next: \(.nextStageId)"'
   

3. Add stages in promotion order. stage add inserts a stage before --next-stage-id, so anchor each new stage to the one that should follow it. To build Integration → UAT → Production, add Production first (or anchor to the terminal stage), then insert UAT before Production, then Integration before UAT:

   # Assume Production stage id is 0Xc...PROD (from step 2 or a prior add)
   sf devops pipeline stage add --pipeline-id "$PIPELINE_ID" \
     --name "UAT" --next-stage-id 0XcPROD --json
   sf devops pipeline stage add --pipeline-id "$PIPELINE_ID" \
     --name "Integration" --next-stage-id 0XcUAT --json
   

4. Bind an environment to each stage (re-fetch stage IDs with pipeline get). In CI, add --no-browser:

   sf devops stage environment add --pipeline-id "$PIPELINE_ID" \
     --stage-id 0XcINT --environment-name integration-org --org-type Sandbox --no-browser --json
   sf devops stage environment add --pipeline-id "$PIPELINE_ID" \
     --stage-id 0XcUAT --environment-name uat-org --org-type Sandbox --no-browser --json
   sf devops stage environment add --pipeline-id "$PIPELINE_ID" \
     --stage-id 0XcPROD --environment-name prod-org --org-type Production --no-browser --json
   

5. Activate once every stage has an environment:

   sf devops pipeline update --pipeline-id "$PIPELINE_ID" --activate --json
   

6. Verify the final shape:

   sf devops pipeline get --pipeline-id "$PIPELINE_ID" --json | \
     jq -r '.result | "\(.name) [\(.isActive)]: \([.stages[].name] | join(", "))"'
   

Report: "Release Pipeline created and activated: Integration → UAT → Production, environments bound."

---

Workflow 2: Insert a Staging Stage Before Production

User request: "Add a Staging stage between UAT and Production on the Release Pipeline"

Steps:

1. Find the pipeline and stage IDs:

   PIPELINE_ID=$(sf devops pipeline list --json | \
     jq -r '.result.pipelines[] | select(.Name == "Release Pipeline") | .Id' | head -n1)
   sf devops pipeline get --pipeline-id "$PIPELINE_ID" --json | \
     jq -r '.result.stages[] | "\(.name) (\(.id)) -> next: \(.nextStageId)"'
   # Integration (0XcINT) -> next: 0XcUAT
   # UAT (0XcUAT) -> next: 0XcPROD
   # Production (0XcPROD) -> next: null
   

2. Insert Staging before Production:

   sf devops pipeline stage add --pipeline-id "$PIPELINE_ID" \
     --name "Staging" --next-stage-id 0XcPROD --json
   

3. Bind the staging environment (get the new stage ID from pipeline get):

   sf devops stage environment add --pipeline-id "$PIPELINE_ID" \
     --stage-id 0XcSTG --environment-name staging-org --org-type Sandbox --no-browser --json
   

4. Verify Staging now sits between UAT and Production.

Constraint: This works only if the pipeline is not yet locked. Stages can't be modified after the pipeline is activated and changes have been promoted through it.

Report: "Staging stage inserted before Production, bound to staging-org."

---

Workflow 3: Attach a Project to a Pipeline

User request: "Connect Project Alpha to the Release Pipeline"

Steps:

1. Resolve IDs:

   PIPELINE_ID=$(sf devops pipeline list --json | \
     jq -r '.result.pipelines[] | select(.Name == "Release Pipeline") | .Id' | head -n1)
   PROJECT_ID=$(sf devops project list --json | \
     jq -r '.result.projects[] | select(.Name == "Project Alpha") | .Id' | head -n1)
   

2. Attach:

   sf devops pipeline project add --pipeline-id "$PIPELINE_ID" --project-id "$PROJECT_ID" --json
   

3. Verify via pipeline get that Project Alpha appears in .result.connectedProjects[].

Constraint: A project attaches to only one pipeline. If attach fails with "already attached," detach it from the other pipeline first: sf devops pipeline project delete --pipeline-id <other> --project-id "$PROJECT_ID" --json.

Report: "Project Alpha attached to Release Pipeline."

---

Workflow 4: Rename and Deactivate a Pipeline

User request: "Deactivate the Release Pipeline and rename it to Legacy Pipeline"

Steps:

1. Combine deactivate + rename in one command:

   sf devops pipeline update --pipeline-id 0XB000000000001 \
     --deactivate --name "Legacy Pipeline" --json
   

2. Verify via pipeline get that .result.isActive is false and the name updated.

Report: "Pipeline deactivated and renamed to 'Legacy Pipeline'."

---

Workflow 5: Idempotent Pipeline Setup (Safe Re-Run in CI)

User request: "Ensure the Release Pipeline exists — runs on every CI job"

Steps:

PIPELINE_NAME="Release Pipeline"

EXISTING_ID=$(sf devops pipeline list --json | \
  jq -r ".result.pipelines[] | select(.Name == \"$PIPELINE_NAME\") | .Id" | head -n1)

if [ -n "$EXISTING_ID" ]; then
  echo "Pipeline already exists: $EXISTING_ID"
else
  sf devops pipeline create --name "$PIPELINE_NAME" \
    --repo https://github.com/myorg/myrepo --json
fi

Report: either the existing pipeline ID or the newly created one — no duplicate created.

---

Notes for Autonomous Runs

• Confirm org auth with sf org display --json before the first command.
• Stage IDs come from sf devops pipeline get — always fetch them before stage add / stage update / stage delete / stage environment add.
• stage add inserts before --next-stage-id; plan the anchor stage to get the order you want.
• stage environment add opens a browser OAuth flow — always pass --no-browser in CI and complete auth via the printed redirect URL.
• Finish all stage/environment configuration before activating; an active, promoted pipeline locks its stage structure.
• Deactivate before deleting an environment; the pipeline must be inactive.
• Treat a same-name create as idempotent — check-before-create and report the existing pipeline.