Skip to content

docker.md

Latest commit

 

History

History
67 lines (45 loc) · 1.97 KB

docker.md

File metadata and controls

67 lines (45 loc) · 1.97 KB

Docker Runners

This guide assumes outrunner is already installed and running. If not, start with one of the setup guides.

Runner image

You need a Docker image with the GitHub Actions runner agent. You can use the official image or build your own.

Option A: Official image

docker pull ghcr.io/actions/actions-runner:latest

Option B: Build a custom image

See Build a custom Docker runner image.

Configuration

In your outrunner config, add a runner with the docker backend:

runners:
  linux:
    labels: [self-hosted, linux]
    docker:
      image: ghcr.io/actions/actions-runner:latest

Or with a custom image:

runners:
  linux:
    labels: [self-hosted, linux]
    docker:
      image: outrunner-runner:latest
      runner_cmd: ./run.sh

runner_cmd defaults to ./run.sh and can be omitted for most images.

Docker socket

outrunner auto-detects the Docker socket. On Linux it uses /var/run/docker.sock. On macOS it detects Colima, Docker Desktop, or Podman sockets automatically.

To override, set the DOCKER_HOST environment variable.

How it works

  1. outrunner pulls the image if not available locally.
  2. Creates a container with the JIT registration token.
  3. The runner inside the container registers with GitHub, picks up the job, and runs it.
  4. On job completion, outrunner stops the container. It auto-removes itself (AutoRemove: true).

Notes

  • Docker containers share the host kernel. For stronger isolation, use libvirt or Tart.
  • On macOS, Docker runs inside a Linux VM (Colima, Docker Desktop). Performance is slightly lower but rarely noticeable for CI.
  • On Apple Silicon, docker build produces ARM64 images by default.

Next steps