How to Set Up Ephemeral Environments for Testing

An ephemeral environment is a temporary deployment target that spins up on demand, runs your full deployment pipeline against a real AWS account, and resets when you’re done. You get a production-like environment for every feature branch or PR without maintaining a fleet of long-lived staging servers.

The typical workflow: a developer opens a PR, the ephemeral environment claims a lock, deploys the PR’s code, and sits there until the PR is closed. Then it redeploys the main branch and releases the lock for the next person. No manual setup, no “who’s using staging right now?” Slack messages.

PR-Triggered Environments

The most common setup ties ephemeral environments to pull requests. When a PR is opened against a matching branch pattern, Dev Ramps automatically claims the environment, builds artifacts, and deploys.

Add an ephemeral_environments block to your pipeline.yaml:

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
      vars:
        env: test

Here’s what each field does:

• triggers: pull_request means this environment activates when a PR is opened or updated. The target_branches filter controls which PRs qualify. Wildcards work, so feat-* matches feat-login, feat-dashboard, etc.
• release: Two conditions here. pr_closed releases the environment when the PR is closed or merged. timeout is a safety net that releases after 24 hours of inactivity, in case someone forgets to close the PR.
• on_release: deploy_main tells Dev Ramps to redeploy the latest main branch commit after release. This resets the environment to a known-good state for the next session.
• account_id and region: The AWS account and region where this environment deploys. This can be the same account as your staging environment or a dedicated test account.

When the PR is opened, Dev Ramps posts a deployment status update on the PR. Each subsequent push to the PR branch triggers a new deployment to the same environment.

API-Triggered Environments

PR triggers cover the human workflow. But if you’re using AI coding agents or automation scripts that need to deploy and test changes, API-triggered environments are more flexible.

ephemeral_environments:
  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

The key difference: on: api for both trigger and release. Nothing happens automatically. Instead, an external caller claims the environment, deploys commits, and releases when done.

To claim and deploy:

POST /organizations/{orgId}/pipelines/{pipelineId}/ephemeral-environments/agent-env/sessions
Body: { "commitId": "abc123", "context": "Testing auth refactor" }

To deploy subsequent commits within the same session:

POST /organizations/{orgId}/pipelines/{pipelineId}/ephemeral-environments/agent-env/sessions/{sessionId}/deploy
Body: { "commitId": "def456" }

To release when done:

DELETE /organizations/{orgId}/pipelines/{pipelineId}/ephemeral-environments/agent-env/sessions/{sessionId}

Notice the after_idle_hours: 1 timeout. For agent-driven environments, a shorter timeout makes sense. If the agent crashes or the script errors out, the environment releases itself after an hour instead of sitting there indefinitely.

Session Lifecycle

Every ephemeral environment interaction follows four phases:

1. Claim: A lock is acquired on the environment. Only the lock holder can deploy. This prevents two PRs from stomping on the same infrastructure simultaneously.
2. Deploy: The lock holder’s commits deploy through the same steps as your regular pipeline stages (artifact builds, Terraform, ECS deploy, etc.).
3. Release: The lock is released, either by closing the PR, calling the API, or hitting the idle timeout.
4. Reset: If on_release: deploy_main is configured, Dev Ramps deploys the latest main branch commit. This brings the environment back to a clean state.

The reset step matters more than it might seem. Without it, the next person to use the environment would inherit whatever half-finished feature the previous developer left behind. Terraform state, ECS task definitions, database schemas: all of it carries over unless you explicitly reset.

Skipping Steps and Setting Variables

Ephemeral environments run the same deployment steps as your production stages. But some steps don’t make sense in a test context. A 5-minute bake period that’s essential for production is just wasted time when you’re iterating on a feature branch.

Use the skip field to exclude steps by name:

ephemeral_environments:
  pr-env:
    skip: ["1 Minute Bake", "Smoke Tests"]
    vars:
      env: test
      replicas: 1
      log_level: debug

Variables set in vars are available in your step configurations via ${{ vars.key }}. Set replicas: 1 to save on compute costs, or log_level: debug to get more visibility during testing. These override any defaults from your regular stages.

You also have access to the full set of pipeline expressions: ${{ trigger.sha }}, ${{ trigger.branch }}, ${{ stage.artifacts["Name"].image_url }}, and organization/stage secrets.

Handling Contention

Only one session can hold a lock at a time. If a second developer opens a PR while someone else’s environment is active, Dev Ramps posts a contention comment on the new PR explaining that the environment is in use. The comment includes a link to force-claim the environment.

Force-claiming releases the existing lock (notifying the previous holder) and starts a new session. This is intentionally disruptive, so it requires an explicit action rather than happening silently.

POST /organizations/{orgId}/pipelines/{pipelineId}/ephemeral-environments/pr-env/force-claim
Body: { "commitId": "abc123" }

If your team frequently hits contention, you have a few options: define multiple ephemeral environments in the same pipeline (each with its own AWS account or naming scheme), reduce the idle timeout so environments release faster, or use the Slack notifications to get alerted when environments become available:

notifications:
  slack:
    channel: "#deployments"
    events:
      - ephemeral_claimed
      - ephemeral_released

Conclusion

Ephemeral environments eliminate the shared staging bottleneck. Configure one in your pipeline.yaml, point it at a test AWS account, and every PR gets its own deployment. For teams using AI agents, the API-triggered variant gives programmatic control over the full claim/deploy/release cycle.

Start with a single PR-triggered environment and a 24-hour idle timeout. Once the team is using it regularly, add Slack notifications for contention and consider a second environment if demand outpaces the single lock. For details on the full configuration reference, see the ephemeral environments docs.