Actions Runner Controller Overview
The Actions Runner Controller runs Gitea Actions runners in a Kubernetes cluster and scales them with the job queue: it adds runners while jobs are waiting and removes them once they are idle. You describe a group of runners with a Runner resource, and the controller creates, registers and removes the runner pods.
It works with any Kubernetes cluster that meets the requirements, managed or self-hosted, and does not depend on a cloud provider.
| Term | Meaning |
|---|---|
Runner |
The Kubernetes resource you create. It describes a group of runners and how they scale. |
| runner | A Gitea Actions runner, as listed on the runner pages of Gitea. |
| runner pod | A pod the controller creates for a Runner. Each runs one runner. The events, log and field descriptions (kubectl explain) of the controller call it a worker: worker 3 is the runner pod <name>-0003. |
| job pod | With the Kubernetes backend, a pod the runner creates to run one job. |
| registration | The identity of a runner in Gitea. The controller obtains it with the registration token and keeps it in a Secret. |
| runner configuration | The configuration file of a runner (config.yaml), which the controller generates from the Runner. |
| action cache | The code of the actions that jobs use with uses:, downloaded by the runner. It is unrelated to the workflow cache. |
| workflow cache | The files that workflows save and restore through the cache API, such as with actions/cache, or with setup-go, setup-node and other actions when their caching is on. It is kept by a cache server or in an S3 bucket. |
How it works
Section titled “How it works”- You create a
Runnerresource in a namespace. It names the Gitea instance, a registration token, and the labels that jobs select withruns-on. - Every few seconds the controller asks Gitea how many jobs are waiting for those labels, and whether its runners are online and busy. This uses an API of Gitea Enterprise, so it needs a valid license.
- From the answer it works out how many runner pods are needed, between
minSizeandmaxSize. When jobs are waiting it adds the runner pods they need in one step. When the runners are idle it removes them one at a time. See Scaling for the details. - For each runner pod, the controller registers a runner with Gitea and generates its runner configuration. Only the controller uses the registration token: runner pods receive the credentials of their own runner only.
- The runner in the pod fetches and runs jobs with the same protocol as any other Gitea Actions runner.
Runner pods are named after the Runner with a number, <name>-0001, <name>-0002 and so on. When a runner pod is removed, its registration is kept, and its cache volumes for a week by default (storage.cacheTTL). The next time that number is needed, its runner pod is recreated as the same runner in Gitea, with its caches.
Scope of the runners
Section titled “Scope of the runners”The registration token decides which jobs the runners of a Runner take, and which waiting jobs the controller counts:
| Token from | Runners serve |
|---|---|
| Site Administration → Actions → Runners | All repositories of the instance |
| Organization settings → Actions → Runners | The repositories of the organization |
| Repository settings → Actions → Runners | The repository |
The runners are listed on the same page the token comes from, under the names of their pods.
Backends
Section titled “Backends”A Runner runs its jobs with one of two backends, and sets exactly one of them:
- Docker-in-Docker: each runner pod runs its own Docker daemon, and jobs run as containers of that daemon. This is how a runner installed on a server works, but the runner pods must be privileged.
- Kubernetes: the runner creates a pod for each job through the Kubernetes API. Neither the runner pods nor the job pods are privileged, but jobs have no Docker daemon to use.
| Docker-in-Docker | Kubernetes | |
|---|---|---|
| Configured with | spec.runtime |
spec.kubernetesRuntime |
| Runner image | gitea/runner:<version>-dind, 5.3.0 or later, 6.0.0 or later recommended |
gitea/runner:<version>, 5.3.0 or later, 6.0.0 or later recommended |
| Where a job runs | A container of the Docker daemon in the runner pod | A job pod of its own |
| Privileged pods | Required | Not required. Runner pods meet the restricted Pod Security Standard, job pods baseline |
| Jobs per runner pod | 1 | capacity, 4 by default |
| Docker in jobs | Available: docker build, Docker actions, service volumes |
Not available, see limitations |
| Isolation between jobs | Separate containers on a shared Docker daemon, one job at a time per pod | Separate pods, which can use a sandboxed runtime class such as Kata Containers |
| Persistent volumes per runner pod | Docker data root and action cache | Action cache |
| Pulled job images are cached | On the runner’s Docker volume, follows the runner | On the node, follows the node |
Choose the Kubernetes backend when the cluster does not allow privileged pods, or when jobs should run in pods of their own. Choose Docker-in-Docker when workflows build container images or use Docker actions. Both can be used side by side, with a Runner of each kind and different labels, see Using both backends.
What the controller creates
Section titled “What the controller creates”In the namespace of each Runner:
| Resource | Docker-in-Docker | Kubernetes |
|---|---|---|
| Runner pods | Up to maxSize, one job at a time each |
Up to maxSize, capacity jobs at a time each |
| Job pods | None | One per running job, created by the runner and deleted when the job ends |
| Persistent volume claims per runner pod | Two: <runner pod>-cache for the Docker data root, <runner pod>-action-cache for the action cache |
One: <runner pod>-action-cache |
| Secret per runner | <runner pod>-registration, the runner’s registration |
Same |
| ConfigMap per runner pod | <runner pod>-config, the generated runner configuration |
Same |
| ServiceAccount and RoleBinding | None | <name>-worker, for the runner to create job pods |
| Cache server | For the workflow cache, one per Runner: pod <name>-cache-server, Service <name>-cache-server-svc, Secret <name>-cache-server-secret, volume <name>-cache-server-data. Not created with S3-compatible storage (recommended), an external cache server or your own runner configuration |
Same |
Runner pods carry the labels app: <name> and runner-index: <number>, and the cache server pod app: <name> and name: <name>-cache-server, for NetworkPolicies and other selectors.
All of them are owned by the Runner, and deleting the Runner deletes them. The runners registered in Gitea are not deleted: they stay as offline runners until you delete them in Gitea.
Requirements
Section titled “Requirements”- Gitea Enterprise with a valid license. Without one the controller cannot read the job queue, so it neither creates nor scales runner pods, and reports an
InspectGiteaFailedevent with status403on theRunner. Gitea Enterprise 27.3.0 or later is required, 28.3.1 or later is recommended. - A registration token at the scope the runners should serve.
- Kubernetes 1.30 or later.
- Network access from the cluster to your Gitea Enterprise instance. All connections start from the cluster, so Gitea does not need to reach the cluster, and no Ingress or load balancer is needed. The cluster must also be able to pull the runner image and the job images, and to download the actions that jobs use, from
https://github.comby default. - A StorageClass that provisions
ReadWriteOncevolumes dynamically, see Storage and caching. - The requirements of the backend: Docker-in-Docker or Kubernetes.
Next steps
Section titled “Next steps”- Install the controller.
- Create a
Runnerwith the Docker-in-Docker backend or the Kubernetes backend. - Adjust it with the configuration and storage and caching options. Runner reference lists every field.