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.
| Field | Meaning |
|---|---|
labels | Required. A job starts a runner only when it carries every one of these labels. |
runtime | firecracker (the default) or docker |
image | The runner image. Defaults to ghcr.io/actions/actions-runner. |
timeout_seconds | Up to 3600. Defaults to 600. |
runner_group_id | The runner group to register in. Defaults to 1. |
cpus, memory_bytes | Limits 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.
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.