nprasad2077/docs
1
1 Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-11-05 17:45:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Simplify the runner docs and fix their outdated facts (#600)

Browse Source 
The runner pages had drifted from the runner. They claimed Podman is unsupported, a registration retry limit of 10, a `container.env` proxy override that has no effect, and they used the deprecated `generate-config` command, while the actual instructions were buried under implementation details.

The develop and 5.x pages are rewritten from the current runner sources (`main` is `v5.2.0`). They are shorter and aimed at operators, with a new page covering what jobs get. The reference generator now documents the `config` command, and the quickstart pages in every language use the `gitea-runner` binary name.

Reviewed-on: https://gitea.com/gitea/docs/pulls/600
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
This commit is contained in:
silverwind authored and silverwind committed 2026-10-21 05:25:45 +00:00
1 parent a874918bb7
commit be6aefc7e8
53 files changed
+1531 -1661
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

runner-docs_versioned_docs/version-5/index.md
+23 -27
View File
@@ -5,47 +5,43 @@ slug: /
# Gitea Runner
The [Gitea Runner](https://gitea.com/gitea/runner) executes the jobs of [Gitea Actions](/usage/actions/overview).
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.
[Gitea Runner](https://gitea.com/gitea/runner) runs [Gitea Actions](/usage/actions/overview) jobs.
It asks a Gitea instance for jobs, runs them, and sends their logs and results back.
:::info
These pages describe the runner `5.x` series. Pick another release, or the development version, in the **Runner Version** dropdown.
These pages describe the runner `5.x` series. Select another release, or the development version, in the **Runner Version** dropdown.
:::
## Requirements
A runner needs a Gitea instance with Actions enabled, a [registration token](registration.md), 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:
- Gitea 1.21 or later with [Actions enabled](/administration/config-cheat-sheet#actions-actions), the default setting.
- Git 2.34.1 or later on the runner's `PATH`.
- Docker, or Podman with `podman.socket` enabled, for jobs in containers, Docker actions, and `docker://` steps.
```ini
[actions]
ENABLED=true
```
Jobs need these tools wherever steps run, in the job image or on the host:
The runner downloads actions and reusable workflows with Git, so it needs Git 2.34.1 or newer on its `PATH`; jobs that use `builtin:checkout` need Git in their image as well. The official runner images include it.
- `bash` or `sh` for `run` steps, or `pwsh` or `powershell` on Windows.
- `node` for JavaScript actions and `hashFiles()`.
- `git` 2.34.1 or later for [`builtin:checkout`](jobs.md#built-in-checkout), plus `git-lfs` for its `lfs` input and `ssh` for its `ssh-key` input.
Other OCI engines that implement the Docker API may work, but are untested. Podman is not a supported configuration.
## Where jobs run
## Execution modes
The runner's [labels](labels.md) determine where each job runs. One runner can use a mix of these environments:
A runner can run jobs in three different ways. The mode is not a global setting: it follows from the [labels](labels.md) the runner is registered with, so a single runner can offer both container and host labels.
| Label | Where the job runs |
| --- | --- |
| `docker://<image>` | In a container |
| `kubernetes://<image>` | In a pod in a Kubernetes cluster |
| `host` | Directly on the runner's machine |
| 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 |
Host jobs run as the runner's user without isolation. Use them only for trusted repositories.
## Getting started
1. [Install the runner](installation/binary.md) as a binary, [in Docker](installation/docker.md), or [on Kubernetes](installation/kubernetes.md).
2. [Register it](registration.md) against your instance with a registration token.
3. [Configure it](configuration.md), and pick the [labels](labels.md) that decide which jobs it accepts.
4. Optionally set up a [shared cache](cache.md), [job hooks](hooks/job-hooks.md), a [post-task script](hooks/post-task-script.md), or [metrics and health checks](monitoring.md).
1. Install the runner [from a binary](installation/binary.md), [with Docker](installation/docker.md), or [on Kubernetes](installation/kubernetes.md).
2. [Register it](registration.md) with your Gitea instance.
3. Start it with `gitea-runner daemon`.
Every command and flag is listed in the [command line reference](reference/cli.md).
The runner works without a configuration file. [Configuration](configuration.md) explains when you need one.
## 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](upgrade.md) first: `2.0.0`, `3.0.0`, `4.0.0` and `5.0.0` all contain breaking changes.
The runner is released independently of Gitea. Read [Upgrading](upgrade.md) before moving to a new major version.