docs(runner): job containers and service containers
- commit
- 77f4a1964e5638d5d322b2c4d7a704524080ee5d
- author
- brice · · 2026-10-14 06:00 UTC
- parent
- 9596a73
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
1 file · +42 -0
M README.md +42 -0
| @@ -256,6 +256,48 @@ image: | |||
| 256 | 256 | tzdata, zip/unzip. Full parity with the hosted images (`actions/runner-images`) | |
| 257 | 257 | is a later phase. | |
| 258 | 258 | ||
| 259 | + | ## Job containers and service containers | |
| 260 | + | ||
| 261 | + | `container:` and `services:` work as on GitHub-hosted Linux runners | |
| 262 | + | (`internal/executor/containers_*.go`, a port of `ContainerOperationProvider`, | |
| 263 | + | `ContainerInfo`, `DockerCommandManager` and `ContainerStepHost` of | |
| 264 | + | actions/runner, with their line numbers in the comments). The containers are | |
| 265 | + | created in the **sandbox's own `dockerd`**, so nothing reaches the host: in `vm` | |
| 266 | + | mode (the mode of hosts without Docker Engine) the daemon runs inside the | |
| 267 | + | micro-VM, in `container` mode it is the nested daemon of the job. | |
| 268 | + | ||
| 269 | + | - **Initialize containers** (a step after "Set up job"): docker version check | |
| 270 | + | (API ≥ 1.35), cleanup of labelled leftovers, network `github_network_<32 hex>`, | |
| 271 | + | for each container `docker pull` (3 tries, random 1–10 s back off), | |
| 272 | + | `docker create`/`start`, `docker port` and the health checks of the services | |
| 273 | + | (exponential back off 2–32 s, "`<alias>` service is healthy."). Registry | |
| 274 | + | `credentials:` go to a private `docker --config` directory under RUNNER_TEMP | |
| 275 | + | (password through stdin, masked in every log, directory removed after the pull). | |
| 276 | + | - **Stop containers** (post step, `always()`): service logs, `docker rm --force`, | |
| 277 | + | `docker network rm`. It runs after a failure, a cancellation, a step timeout | |
| 278 | + | and the job timeout. | |
| 279 | + | - **Steps in the job container**: `run:` steps and node actions go through | |
| 280 | + | `docker exec -i --workdir … -e NAME… <id> …` (values are passed in the | |
| 281 | + | environment of the docker process, translated to `/__w`, `/__t`, `/__e`, | |
| 282 | + | `/github/home`, `/github/workflow`, never on the command line). The shell is | |
| 283 | + | looked up by the container: `sh -e {0}` unless the step says otherwise. Node | |
| 284 | + | actions use the externals mounted read-only at `/__e`, `node<N>_alpine` when | |
| 285 | + | `/etc/*release` says alpine. Docker actions run as siblings on the job network. | |
| 286 | + | - Contexts: `job.container.{id,network}`, `job.services.<alias>.{id,network,ports}` | |
| 287 | + | (host ports from `docker port`). | |
| 288 | + | - **Untrusted input.** `options:` is split into arguments like .NET splits a | |
| 289 | + | command line and passed to `docker create` as an argument vector, never through | |
| 290 | + | a shell, so a workflow cannot inject a second command; it can still pass any | |
| 291 | + | `docker create` flag (`--privileged`, `--pid host`, `--device`, …) and bind | |
| 292 | + | volumes (`volumes: /:/host`), exactly as on a self-hosted GitHub runner. That | |
| 293 | + | is contained by the sandbox (its own daemon, its own disk), not by the runner: | |
| 294 | + | **host paths in `volumes:` and `options:` are paths of the sandbox**. A job | |
| 295 | + | that mounts `/` exposes the sandbox's filesystem to its own container only. | |
| 296 | + | The runner warns, as GitHub does, about a volume that mounts `/`. | |
| 297 | + | - Not ported: container hooks (`ACTIONS_RUNNER_CONTAINER_HOOKS`), the | |
| 298 | + | "already running in a container" refusal (the sandbox's daemon is local to the | |
| 299 | + | executor). | |
| 300 | + | ||
| 259 | 301 | ## Job limits | |
| 260 | 302 | ||
| 261 | 303 | Each job gets its own resources, set for the runner as a whole: | |
| @@ -256,6 +256,48 @@ image: | |||||
| 256 | tzdata, zip/unzip. Full parity with the hosted images (`actions/runner-images`) | 256 | tzdata, zip/unzip. Full parity with the hosted images (`actions/runner-images`) | ||
| 257 | is a later phase. | 257 | is a later phase. | ||
| 258 | 258 | ||||
| 259 | + | ## Job containers and service containers | |||
| 260 | + | ||||
| 261 | + | `container:` and `services:` work as on GitHub-hosted Linux runners | |||
| 262 | + | (`internal/executor/containers_*.go`, a port of `ContainerOperationProvider`, | |||
| 263 | + | `ContainerInfo`, `DockerCommandManager` and `ContainerStepHost` of | |||
| 264 | + | actions/runner, with their line numbers in the comments). The containers are | |||
| 265 | + | created in the **sandbox's own `dockerd`**, so nothing reaches the host: in `vm` | |||
| 266 | + | mode (the mode of hosts without Docker Engine) the daemon runs inside the | |||
| 267 | + | micro-VM, in `container` mode it is the nested daemon of the job. | |||
| 268 | + | ||||
| 269 | + | - **Initialize containers** (a step after "Set up job"): docker version check | |||
| 270 | + | (API ≥ 1.35), cleanup of labelled leftovers, network `github_network_<32 hex>`, | |||
| 271 | + | for each container `docker pull` (3 tries, random 1–10 s back off), | |||
| 272 | + | `docker create`/`start`, `docker port` and the health checks of the services | |||
| 273 | + | (exponential back off 2–32 s, "`<alias>` service is healthy."). Registry | |||
| 274 | + | `credentials:` go to a private `docker --config` directory under RUNNER_TEMP | |||
| 275 | + | (password through stdin, masked in every log, directory removed after the pull). | |||
| 276 | + | - **Stop containers** (post step, `always()`): service logs, `docker rm --force`, | |||
| 277 | + | `docker network rm`. It runs after a failure, a cancellation, a step timeout | |||
| 278 | + | and the job timeout. | |||
| 279 | + | - **Steps in the job container**: `run:` steps and node actions go through | |||
| 280 | + | `docker exec -i --workdir … -e NAME… <id> …` (values are passed in the | |||
| 281 | + | environment of the docker process, translated to `/__w`, `/__t`, `/__e`, | |||
| 282 | + | `/github/home`, `/github/workflow`, never on the command line). The shell is | |||
| 283 | + | looked up by the container: `sh -e {0}` unless the step says otherwise. Node | |||
| 284 | + | actions use the externals mounted read-only at `/__e`, `node<N>_alpine` when | |||
| 285 | + | `/etc/*release` says alpine. Docker actions run as siblings on the job network. | |||
| 286 | + | - Contexts: `job.container.{id,network}`, `job.services.<alias>.{id,network,ports}` | |||
| 287 | + | (host ports from `docker port`). | |||
| 288 | + | - **Untrusted input.** `options:` is split into arguments like .NET splits a | |||
| 289 | + | command line and passed to `docker create` as an argument vector, never through | |||
| 290 | + | a shell, so a workflow cannot inject a second command; it can still pass any | |||
| 291 | + | `docker create` flag (`--privileged`, `--pid host`, `--device`, …) and bind | |||
| 292 | + | volumes (`volumes: /:/host`), exactly as on a self-hosted GitHub runner. That | |||
| 293 | + | is contained by the sandbox (its own daemon, its own disk), not by the runner: | |||
| 294 | + | **host paths in `volumes:` and `options:` are paths of the sandbox**. A job | |||
| 295 | + | that mounts `/` exposes the sandbox's filesystem to its own container only. | |||
| 296 | + | The runner warns, as GitHub does, about a volume that mounts `/`. | |||
| 297 | + | - Not ported: container hooks (`ACTIONS_RUNNER_CONTAINER_HOOKS`), the | |||
| 298 | + | "already running in a container" refusal (the sandbox's daemon is local to the | |||
| 299 | + | executor). | |||
| 300 | + | ||||
| 259 | ## Job limits | 301 | ## Job limits | ||
| 260 | 302 | ||||
| 261 | Each job gets its own resources, set for the runner as a whole: | 303 | Each job gets its own resources, set for the runner as a whole: | ||