Stages

Stages define where your application deploys. Each stage represents an environment in a specific AWS account and region. Stages execute sequentially -- the first stage must succeed before the second begins.

Stage Configuration

stages:
  - name: staging
    account_id: "111111111111"
    region: us-east-1
    deployment_time_window: NONE
    vars:
      env: staging
    skip: ["Bake Period"]
    auto_rollback_alarm_name: my-alarm

Stage fields

Field	Required	Description
name	Yes	Unique name for the stage. Must be lowercase alphanumeric characters and hyphens. Used in URLs, logs, and expressions.
account_id	Yes	The AWS account ID to deploy to.
region	Yes	The AWS region to deploy to.
deployment_time_window	No	When deployments are allowed. Overrides stage_defaults.
vars	No	Stage-specific variables accessible via ${{ vars.key }}.
skip	No	Array of step names or IDs to skip in this stage.
auto_rollback_alarm_name	No	CloudWatch alarm name that triggers automatic rollback. See Auto-Rollback.

Stage Defaults

Use stage_defaults to set properties that apply to all stages. Individual stages can override these values.

stage_defaults:
  deployment_time_window: PACIFIC_WORKING_HOURS

stages:
  - name: staging
    deployment_time_window: NONE      # Overrides the default
    account_id: "111111111111"
    region: us-east-1

  - name: production
    # Inherits PACIFIC_WORKING_HOURS from stage_defaults
    account_id: "222222222222"
    region: us-east-1

Available defaults

Field	Description
deployment_time_window	Default deployment time window for all stages.

Deployment Time Windows

Deployment time windows restrict when deployments can run in a stage. If a deployment is triggered outside the window, it queues until the window opens.

Value	Hours	Days
NONE	No restriction -- deployments run anytime.	All days
PACIFIC_WORKING_HOURS	9:00 AM -- 5:00 PM Pacific Time	Weekdays only
PACIFIC_WORKING_HOURS_REDUCED	10:00 AM -- 4:00 PM Pacific Time	Weekdays only

Pacific Time Only

Deployment windows are currently available in Pacific Time only. Custom time windows and additional timezone support are planned for a future release. Holidays are not accounted for — "Weekdays only" means Monday through Friday regardless of holidays.

If you need to deploy outside a window in an emergency, use Bypass Deployment Blockers.

Example: Allow unrestricted staging deploys, but limit production to business hours:

stages:
  - name: staging
    deployment_time_window: NONE
    # ...

  - name: production
    deployment_time_window: PACIFIC_WORKING_HOURS
    # ...

Stage Variables

Variables let you customize step behavior per stage. Define them in the vars field and reference them in steps using ${{ vars.key }}.

stages:
  - name: staging
    account_id: "111111111111"
    region: us-east-1
    vars:
      env: staging
      service_name: my-app
      azs: ["us-east-1a", "us-east-1b"]

  - name: production
    account_id: "222222222222"
    region: us-east-1
    vars:
      env: production
      service_name: my-app
      azs: ["us-east-1a", "us-east-1b", "us-east-1c"]

Variables support any YAML type -- strings, numbers, arrays, and nested objects:

vars:
  env: production
  replicas: 3
  azs: ["us-east-1a", "us-east-1b", "us-east-1c"]
  config:
    database:
      host: db.example.com
      port: 5432

Access nested values with dot notation: ${{ vars.config.database.host }}.

Skipping Steps

Use skip to exclude specific steps from a stage. Reference steps by their name or id.

stages:
  - name: staging
    account_id: "111111111111"
    region: us-east-1
    skip: ["Bake Period", "custom"]     # Skip by name or by id

steps:
  - name: Deploy API
    type: DEVRAMPS:ECS:DEPLOY
    params: { ... }

  - name: A Custom Step
    id: custom
    type: CUSTOM:MY:STEP
    params: { ... }

  - name: Bake Period
    type: DEVRAMPS:APPROVAL:BAKE
    params:
      duration_minutes: 5

In this example, the staging stage skips both the bake period and the custom step. The production stage runs all steps.

This is useful when:

• You don't need a bake period in staging.
• A step only makes sense in certain environments.
• You want to skip expensive or slow steps during development.

Multi-Account Deployments

A common pattern is deploying to separate AWS accounts for different environments:

stages:
  - name: staging
    account_id: "111111111111"    # Dev/staging account
    region: us-east-1
    vars:
      env: staging

  - name: production
    account_id: "222222222222"    # Production account
    region: us-east-1
    vars:
      env: production

Each account needs to be bootstrapped with IAM roles before deployments can run.

Multi-Region Deployments

Deploy to multiple regions by creating a stage per region:

stages:
  - name: staging
    account_id: "111111111111"
    region: us-east-1
    vars:
      env: staging

  - name: prod-us-east-1
    account_id: "222222222222"
    region: us-east-1
    vars:
      env: prod

  - name: prod-us-west-2
    account_id: "222222222222"
    region: us-west-2
    vars:
      env: prod

  - name: prod-eu-west-2
    account_id: "222222222222"
    region: eu-west-2
    vars:
      env: prod

Stages always execute sequentially — parallel stage execution is not supported. This means regions deploy one at a time, which gives you a natural canary pattern: your first production region (e.g., prod-us-east-1) acts as a canary. If issues arise — detected by monitoring, alarms, or manual observation — you can stop the pipeline before the deployment reaches other regions, limiting the blast radius of a bad deployment.