Product / Deployments & automation / Promotions

Promotions: multi-stage CI/CD delivery pipelines

Updated November 2026 · Promotions docs →

Chain pipelines into delivery flows: build, then staging, then production. Promote by hand or automatically when conditions are met.

TL;DR

Connect pipelines with a promotions block.
auto_promote starts the next stage when a condition is true.
Manual promotions wait for a click.
Parameters let one deploy pipeline serve many environments.

Watch: Promotions

What it does

Multiple environments as separate pipelines.
Automatic deployments with conditions on result, branch, tag or changed files. See the conditions DSL.
Manual controls for releases that need a person.
Custom workflows per promotion, each with its own pipeline file.
Parameters so one pipeline file deploys to many environments. See promotions.

How it works

.semaphore/semaphore.yml

promotions:
  - name: Deploy
    pipeline_file: deploy.yml
    auto_promote:
      when: "result = 'passed' and branch = 'main'"
    parameters:
      env_vars:
        - name: ENVIRONMENT
          required: true
          options:
            - staging
            - production
          default_value: staging

Docs for this feature

FAQ

Can promotions run automatically?

Yes. Add auto_promote with a condition, for example result = ‘passed’ and branch = ‘main’.

Can one deploy pipeline serve several environments?

Yes. Add parameters to the promotion and read them as environment variables in the deploy pipeline.

Can I deploy only the services that changed in a monorepo?

Yes. Use change_in inside the auto_promote condition.

Next steps

Read the Promotions docs → · All Deployments & automation features → · Plans and pricing →

Get started

Tell your agent what you want.
It runs your CI.

$curl -fsSL https://raw.githubusercontent.com/semaphoreio/sem-ai/main/install.sh | sh

>/plugin marketplace add semaphoreio/sem-ai

>/plugin install sem-ai@semaphoreio

$codex plugin marketplace add semaphoreio/sem-ai

$codex plugin add sem-ai@semaphoreio

Then ask your agent to set things up — it connects to your org, and you start with $15 of free usage every month. No signup form.