Ephemeral Environments

Ephemeral environments are temporary deployment targets defined in your pipeline YAML. They enable ad-hoc testing and agentic integrations by providing lock-based, on-demand environments that run the same deployment steps as your regular stages.

Configuration

Add an ephemeral_environments block to your pipeline definition:

pipeline:
  ephemeral_environments:
    pr-env:
      triggers:
        - on: pull_request
          target_branches: ["feat-*", "fix-*"]
      release:
        - on: pr_closed
        - on: timeout
          after_idle_hours: 24
      on_release: deploy_main
      account_id: "123456789012"
      region: us-west-2
      skip: ["1 Minute Bake"]
      vars:
        env: test

    agent-env:
      triggers:
        - on: api
      release:
        - on: api
        - on: timeout
          after_idle_hours: 1
      on_release: deploy_main
      account_id: "123456789012"
      region: us-west-2
      vars:
        env: test

Trigger Types

Trigger	Description
pull_request	Triggered when a PR is opened or updated targeting matching branches
api	Triggered via the API or MCP tools

Pull Request Triggers

When on: pull_request is configured, specify target_branches with patterns to match against the PR's target branch. Supports wildcard matching with *.

API Triggers

When on: api is configured, users can claim sessions and deploy commits via the REST API or MCP tools.

Release Conditions

Condition	Description
pr_closed	Release when the associated PR is closed or merged
api	Release via API call
timeout	Release after idle period (requires after_idle_hours)

Lock Behavior

Each ephemeral environment supports a single active lock at a time. When a lock is active:

• The environment is "claimed" by a PR or API session
• Deployments can only be triggered by the lock holder
• Other callers receive a contention error (with option to force-claim)
• Activity updates the idle timeout timer

Fields

Field	Required	Description
triggers	Yes	Array of trigger configurations
release	Yes	Array of release conditions
on_release	Yes	Action on release (deploy_main)
account_id	Yes	AWS account ID for deployment
region	Yes	AWS region for deployment
vars	No	Stage-specific variables
skip	No	Steps to skip in this environment