Transparent Docker Hub pull-through cache

Busy CI stacks share NAT egress and can exhaust Docker Hub’s pull limit. In v3.2, RunsOn can put a named ECR pull-through cache in front of Docker Hub without changing docker pull commands or Dockerfile FROM lines.

Editorial update (August 2026): RunsOn Team rewrote this tip for v3.2. It supersedes the original community Docker Hub workaround ↗ by alecmocatta.

Docker Hub rules require a Secrets Manager credential, even for public images. Create a secret named ecr-pullthroughcache/docker-hub in the same account and Region, containing username and accessToken, then create the regional ECR rule outside the RunsOn module:

data "aws_secretsmanager_secret" "docker_hub" {
  name = "ecr-pullthroughcache/docker-hub"
}

resource "aws_ecr_pull_through_cache_rule" "docker_hub" {
  ecr_repository_prefix = "docker-hub"
  upstream_registry_url = "registry-1.docker.io"
  credential_arn        = data.aws_secretsmanager_secret.docker_hub.arn
}

Then pass that rule into the Flex or Fleet Terraform module and opt runners in:

module "runs_on" {
  source = "runs-on/runs-on/aws//modules/flex"

  # Other RunsOn settings …
  ecr_pull_through_cache_rules = {
    docker_hub = aws_ecr_pull_through_cache_rule.docker_hub
  }
}

jobs:
  image:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/extras=ecr-pull-through
    steps:
      - uses: runs-on/action@v2
      - run: docker pull node:22
      - run: docker build .

On Linux, the runner signs Docker into ECR and starts a local registry mirror. Docker continues to use normal Docker Hub image names; the mirror rewrites them to the docker-hub ECR namespace and ECR imports the upstream image on the first pull. Later pulls are served from ECR.

Do not use the special ROOT prefix. RunsOn rejects it because it would give runners access to every ECR repository in the account. A named prefix keeps IAM access scoped while preserving transparent Docker Hub pulls.

This automation is for Linux runners. Windows workflows must authenticate to ECR and reference the prefixed ECR image path explicitly. Other upstreams such as GHCR also use explicit ECR paths.

See Docker Hub pull-through for the full secret and Terraform setup, BuildKit behavior, and networking requirements.