Skip to main content

Ephemeral Environments

Ephemeral environments provide temporary, lock-based deployment targets for ad-hoc testing and CI agent integrations.

Session Lifecycle​

  1. Claim -- A lock is acquired on the environment (via PR event or API call)
  2. Deploy -- Commits are deployed to the environment using the pipeline's steps
  3. Release -- The lock is released (PR closed, API call, or timeout)
  4. Reset -- If on_release: deploy_main is configured, the latest main branch commit is deployed

PR Workflow​

When a PR is opened targeting a branch matching an ephemeral environment's target_branches:

  1. DevRamps automatically claims the environment
  2. The PR's head commit is deployed
  3. PR comments show deployment status
  4. When the PR is closed, the environment is released

If the environment is already claimed, a contention comment is posted on the PR with a link to force-claim.

API Workflow​

For environments with api triggers:

  1. Claim a session: POST .../ephemeral-environments/{name}/sessions
  2. Deploy commits: POST .../sessions/{sessionId}/deploy
  3. Check status: GET .../sessions/{sessionId}
  4. Release: DELETE .../sessions/{sessionId}

Notifications​

Subscribe to ephemeral events in your pipeline's notification config:

  • ephemeral_claimed -- Environment lock acquired
  • ephemeral_released -- Environment lock released
  • ephemeral_deployment_succeeded -- Deployment completed successfully
  • ephemeral_deployment_failed -- Deployment failed

Force Claiming​

If an environment is locked and you need access, you can force-claim it. This releases the existing lock and creates a new one. The previous lock holder receives a notification.