Configuration

GitHub Actions runners

Start a single-use GitHub self-hosted runner for each queued workflow job that carries your labels, in a Firecracker microVM or container on your server.

When GitHub queues a workflow job whose labels match a subscription, the agent registers a just-in-time self-hosted runner for the repository and starts it as a run. The runner takes one job and exits when the job ends, so the next job starts in a fresh instance.

1. Create a GitHub App

Give the app Administration write permission on repositories, which GitHub requires to register runners, and subscribe its webhook to Workflow jobs. Install it on the repositories that should use your server. Store its private key where only the agent can read it.

2. Configure the agent

events:
  endpoints:
    - name: ci
      provider: github
      secret: your-webhook-secret-here
  github_app:
    app_id: 12345
    private_key_file: /etc/flatrun/github-app.pem
  subscriptions:
    - name: actions
      source: github/ci
      action: github_runner
      labels: [self-hosted, flatrun]
      github_runner:
        runtime: firecracker
        image: ghcr.io/actions/actions-runner
        timeout_seconds: 1800

Restart the agent, then set the app's webhook URL to https://your-server/api/event-hooks/ci with the same secret.

FieldMeaning
labelsRequired. A job starts a runner only when it carries every one of these labels.
runtimefirecracker (the default) or docker
imageThe runner image. Defaults to ghcr.io/actions/actions-runner.
timeout_secondsUp to 3600. Defaults to 600.
runner_group_idThe runner group to register in. Defaults to 1.
cpus, memory_bytesLimits for each runner

3. Use the labels in a workflow

jobs:
  test:
    runs-on: [self-hosted, flatrun]
    steps:
      - uses: actions/checkout@v4
      - run: make test

What the runner gets

The runner has network access, since it has to reach GitHub. Its registration is passed as a secret, and neither it nor the installation token is written to run records or the delivery log. Each runner is a run, so admins see it and its output in Runs.

If the requested runtime is unavailable, the delivery fails and no runner starts. Firecracker needs the host setup described in Runs and Firecracker.

Check the image has what your jobs need. Jobs that need tools ghcr.io/actions/actions-runner lacks must install them or use an image that includes them. The default image does not install or start Docker. Container jobs need Docker Engine inside the runner, which works only under Firecracker: build an image whose start script launches the Docker daemon, waits for it, then starts the runner.
Star us on GitHub