Ephemeral ECR registry

Since v2.8.2, RunsOn can automatically create an ephemeral registry (an ECR repository in your AWS account) to temporarily store images and layers shared across build jobs — no external registry to configure.

Availability#

Linux runners, with Flex and Fleet (Fleet since v3.2.0). It is not part of Magic Cache: images and layers go to ECR, and the registry is shared by every runner of the stack.

Enable it#

jobs:
  ecr-cache:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/extras=ecr-cache
    steps:
      - uses: runs-on/action@v2
      - uses: actions/checkout@v7
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v4
        env:
          IMAGE: ${{ env.RUNS_ON_ECR_CACHE }}:my-app-latest
          CACHE: ${{ env.RUNS_ON_ECR_CACHE }}:my-app-cache
        with:
          context: .
          push: true
          tags: ${{ env.IMAGE }}
          cache-from: type=registry,ref=${{ env.CACHE }}
          cache-to: type=registry,ref=${{ env.CACHE }},mode=max

enable_ecr = true

runners = {
  linux-cache = {
    cpu    = 2
    family = ["m8", "r8"]
    image  = "ubuntu24-full-x64"
    extras = ["ecr-cache"]
  }
}

Use cases#

The ephemeral registry can be used to:

1. Push and pull images that need to be temporarily shared across workflow jobs. For instance, build an image in one job (e.g. for integration tests) and use it in one or many dependent jobs.
2. Cache Docker layers across workflow jobs.

Accessing the ephemeral registry#

Runners automatically get push/pull access to this registry through the EC2 instance profile. The RUNS_ON_ECR_CACHE environment variable contains the full registry URL (e.g. 123456789012.dkr.ecr.us-east-1.amazonaws.com/runs-on-ab12cd34-ephemeral-registry). The repository name is auto-generated per stack, so always reference ${{ env.RUNS_ON_ECR_CACHE }} rather than hardcoding a path. When you include ecr-cache in the extras label, the RunsOn agent logs into the registry before your job starts and adds the variable to the job’s env context. Without the extra, only shell steps on the host see $RUNS_ON_ECR_CACHE: ${{ env.RUNS_ON_ECR_CACHE }} is empty and job containers don’t get it. The extra is Linux only.

Retention#

The ephemeral registry makes tagged and untagged images eligible for expiration 10 days after they are pushed. This policy is the same for CloudFormation and Terraform / OpenTofu installs. AWS can apply the lifecycle policy up to 24 hours after an image becomes eligible.

Pricing example#

The following uses US East (N. Virginia) Amazon ECR private-repository pricing ↗. It excludes EC2, VPC interface endpoints, NAT Gateway, cross-Region or Internet transfer, taxes, and free-tier credits, and optional enhanced scanning. It assumes 20 GB of retained ECR storage and AWS’s 30-day-month proration.

ECR charges $0.10 per GB-month for private-repository storage. Same-Region EC2 runners can push and pull the cache without an ECR data-transfer charge. The 10-day case can reach about $0.73 when AWS applies its lifecycle policy up to 24 hours later.

Considerations#

The registry is shared across all runners launched by the same RunsOn stack, so only store images and layers that can be shared; create multiple environments if you need better isolation.

On the built-in v3 CloudFormation path, the embedded stack creates the free S3 gateway VPC endpoint but not EC2 or ECR interface VPC endpoints. If your runners use private networking and need private ECR access, add the relevant interface endpoints through Terraform / OpenTofu or your own networking stack.