Migrate from Docker-Based Self-Hosted Runners to Managed Runners

Docker-based self-hosted runners give you clean, ephemeral builds - but you still own the Docker hosts, scaling, and image upkeep. Managed runners give you the same without the hosts.

A common self-hosted setup runs the GitHub runner inside a container on VMs you manage, often with docker-in-docker for builds. Managed runners are already ephemeral and isolated per job, so you keep the clean-build property and drop the host fleet.

What changes

Before and after

jobs:
  build:
    runs-on: [self-hosted, docker]   # dind on your hosts
    steps:
      - uses: actions/checkout@v4
      - run: docker build -t app .

Managed equivalent

jobs:
  build:
    runs-on: latchkey-medium   # ephemeral, Docker-ready
    steps:
      - uses: actions/checkout@v4
      - run: docker build -t app .

Migration steps

1. Identify workflows pinned to your Docker self-hosted labels.
2. Swap runs-on: to a managed label that supports Docker builds.
3. Confirm docker build / compose steps work, using Docker layer caching for speed.
4. Roll out, then decommission the Docker hosts.

Gotchas

• Replace host-shared Docker caches with the runner cache so builds stay fast.
• Privileged dind tricks may differ on managed runners - prefer standard docker build.
• Confirm registry auth uses GitHub secrets or OIDC, not a host-baked credential.

What you gain

• Roughly 69% lower per-minute cost than GitHub-hosted runners.
• Warm pools remove queue time - jobs start almost immediately.
• Self-healing detects, fixes, and auto-retries transient and mechanical failures.
• Zero ops: no agents, autoscalers, or controllers to patch and babysit.

Key takeaways

• Managed runners are already ephemeral and isolated per job.
• You keep clean Docker builds and drop the host fleet.
• Docker layer caching keeps build times fast.

Related guides