Gitea Runner

The Gitea Runner executes the jobs of Gitea Actions. It polls a Gitea instance for queued jobs, runs their steps in a container or directly on the machine it is installed on, and streams the logs and the result back.

Note

These pages describe the runner 3.x series. Pick another release, or the development version, in the Runner Version dropdown.

Requirements

A runner needs a Gitea instance with Actions enabled, a registration token, and, for containerized jobs, a Docker daemon. Actions are enabled by default since Gitea 1.21; on older instances they have to be turned on:

[actions]
ENABLED=true

Other OCI engines that implement the Docker API may work, but are untested. Podman is not a supported configuration.

Execution modes

A runner can run jobs in three different ways. The mode is not a global setting: it follows from the labels the runner is registered with, so a single runner can offer both container and host labels.

Mode	How jobs run	Docker daemon	Notes
Docker (recommended)	in a container created from the label’s image	external, e.g. the host’s /var/run/docker.sock	jobs are isolated from each other, but share the daemon
Docker-in-Docker	in a container created by a daemon that lives next to the runner	bundled in the dind / dind-rootless images	strongest isolation, more setup, needs --privileged
Host	directly on the machine, with the tools installed there	only needed for docker:// actions and service containers	no isolation between jobs

Getting started

1. Install the runner as a binary, in Docker, or on Kubernetes.
2. Register it against your instance with a registration token.
3. Configure it, and pick the labels that decide which jobs it accepts.
4. Optionally set up a shared cache, job hooks, a post-task script, or metrics and health checks.

Every command and flag is listed in the command line reference.

Versioning and compatibility

The runner is released independently of Gitea and its version numbers are unrelated to the instance’s. Gitea 1.21 or later is expected — older instances cannot accept the runner’s label declaration — and individual features need a newer instance still, which is called out where they apply.

When moving between major runner versions, read Upgrading first: 2.0.0 and 3.0.0 both contain breaking changes.