semaphore-promotions

name: semaphore-promotions description: Explain Semaphore promotions — chained pipelines for deploys, gates, and environment fan-out — and link to sem-ai commands for triggering and inspecting them. Use when the user asks about Semaphore promotions, deploys, deployment targets, auto-promote, parameterized promotions, staging vs production gates, how to chain pipelines, or environment fan-out.

Semaphore promotions

The model in three sentences

A promotion triggers a separate pipeline (declared in another YAML file) after the current pipeline finishes. Promotions are how Semaphore models deploys, manual gates, multi-environment fan-out, and any "step 2 that runs after step 1 succeeds." They live at the top level of the pipeline YAML — they are not blocks in the current pipeline's DAG.

Vocabulary

Promotion vs block — the load-bearing distinction

If the answer to "should this run only when CI is green?" is yes, you want a promotion. If it should run as part of CI itself, you want a block.

Worked patterns

Auto-promote on main passing

# .semaphore/semaphore.yml
blocks: [...]

promotions:
  - name: Deploy to staging
    pipeline_file: deploy-staging.yml
    auto_promote:
      when: "branch = 'main' AND result = 'passed'"

deploy-staging.yml fires automatically when CI passes on main. Other branches / failed builds don't trigger it.

Manual promotion to production with a parameter

promotions:
  - name: Push to production
    pipeline_file: deploy-prod.yml
    parameters:
      env_vars:
        - name: RELEASE_TAG
          description: Tag to deploy (e.g. v1.2.3)
          required: true
        - name: ROLLOUT
          description: Rollout mode
          required: true
          default_value: canary
          options:
            - canary
            - immediate

No auto_promote → user clicks the promote button in the Semaphore UI (or runs sem-ai pipeline promote) and fills in the form. deploy-prod.yml sees RELEASE_TAG and ROLLOUT as env vars.

Deployment-target-gated promotion

promotions:
  - name: Push to production
    pipeline_file: deploy-prod.yml
    deployment_target: Production         # references a Deployment Target by name

The Production target carries its own RBAC (which users/roles can promote), branch/tag restrictions, secrets binding, and env_vars. Repo-write permission is not enough — the user must also satisfy the target's subject_rules. See sem-ai deploy show <target-id> for what's configured.

Chained promotions (staging → production)

# .semaphore/semaphore.yml          ← CI pipeline
promotions:
  - name: Deploy staging
    pipeline_file: deploy-staging.yml
    auto_promote: { when: "branch = 'main' AND result = 'passed'" }

# .semaphore/deploy-staging.yml     ← staging pipeline
blocks: [...]
promotions:
  - name: Deploy production
    pipeline_file: deploy-prod.yml
    deployment_target: Production    # manual + RBAC-gated

Tree-shaped workflows: CI → staging (auto) → production (manual + gated). Each tier is its own pipeline file with its own blocks, agent, after_pipeline.

auto_promote.when — the conditions DSL

Common keys: result, branch, tag, pull_request, change_in.

Examples:

Pre-flight checks — the other gate

Promoted pipelines are subject to organization and project pre-flight checks in addition to the promotion's own auto_promote / deployment_target rules. Pre-flight checks run during pipeline initialization — before any block starts — and if any check fails, the pipeline never runs at all.

Important:

• Pre-flight checks are not in pipeline YAML. They live in Semaphore Settings (UI / API). YAML changes won't disable them.
• Checks are shell commands run in an init job. Can bind secrets, have standard env vars (SEMAPHORE_PROJECT_NAME, SEMAPHORE_GIT_BRANCH, etc.).
• The SEMAPHORE_PIPELINE_PROMOTION env var is set when the check runs as part of a promoted pipeline init — use it to skip-or-tighten checks for promotions specifically.
• Failure mode: hard fail at init. The pipeline shows up with a failed initialization job and no blocks ever scheduled.

Common uses:

Two non-obvious behaviors for the agent to remember:

• A promotion that "didn't fire" might have started but failed at pre-flight. Check sem-ai pipeline show <promoted-pipeline-id> for an init-job failure with result: failed and a near-zero block count.
• Disabling a pre-flight check is an org/project setting change, not a YAML edit. The user must do it in the Semaphore UI (or via API).

Inspecting and triggering with sem-ai

Diagnostic playbook for the agent

"My deploy didn't fire after green CI" → check the promotion's auto_promote.when expression. Run sem-ai pipeline show <ci-pipeline-id> and confirm branch / result actually match what the condition expects.

"User can't promote — permission denied" → it's the deployment_target's subject_rules, not repo permissions. sem-ai deploy show <target-id> shows the rules; add the user/role via sem-ai deploy update (or the UI).

"How do I deploy a specific version manually?" → if the pipeline has a parameterized promotion: sem-ai pipeline promote <pipeline-id> --target <name> and pass the parameter values. Otherwise: tag the desired commit and let the auto_promote on tag fire.

"What changed between two deploys?" → sem-ai deploy history <target-id> lists each promotion with workflow IDs and commits. Pick two SHAs and git log A..B.

"Promotion shows as failed with no block output" → likely a pre-flight check failure at init time. The pipeline never reached the blocks. Inspect the init job for the failure message; remediation is in Semaphore Settings, not YAML.

Boundaries

• For pipeline structure (what blocks/tasks/jobs/agents are inside the CI pipeline OR the deploy pipeline), use the semaphore-blocks skill.
• For the full YAML anatomy (version, name, agent, global_job_config, after_pipeline, all the moving parts), use the semaphore-pipeline-yaml-anatomy skill (forthcoming).
• For what the deployed pipeline does (build artifacts, container push, terraform, etc.), that's your project's code — out of Semaphore's structural scope.