mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-05 17:45:46 +00:00
Simplify the runner docs and fix their outdated facts (#600)
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
1 parent
a874918bb7
commit
be6aefc7e8
53 files changed
+1531
-1661
No files matched your search
@@ -4,67 +4,38 @@ sidebar_position: 4
|
||||
|
||||
# Labels
|
||||
|
||||
Labels decide **which jobs a runner accepts** and **how it runs them**. A job's `runs-on` value is matched against the runner's label names; the first match wins and selects the execution environment for that job.
|
||||
A runner's labels determine which jobs it accepts and where it runs them. Gitea sends a job to a runner that has the labels specified in the job's `runs-on`. The runner uses the environment of the first matching entry in `runs-on`.
|
||||
|
||||
A label is written as:
|
||||
|
||||
```text
|
||||
<name>[:<schema>[:<args>]]
|
||||
```
|
||||
|
||||
| Part | Meaning |
|
||||
| Label | Job environment |
|
||||
| --- | --- |
|
||||
| `name` | the name a workflow refers to in `runs-on`, e.g. `ubuntu-latest` |
|
||||
| `schema` | either `docker` or `host`, defaulting to `host` when omitted |
|
||||
| `args` | only used by the `docker` schema: the image the job runs in |
|
||||
| `ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest` | Container using the specified image. |
|
||||
| `ubuntu-latest:kubernetes://docker.gitea.com/runner-images:ubuntu-latest` | Pod using the specified image. See [job pods](installation/kubernetes.md#job-pods). |
|
||||
| `macos:host`, or just `macos` | The runner's machine. |
|
||||
|
||||
Two schemas are supported:
|
||||
|
||||
- `docker://<image>` — the job runs in a container created from `<image>`:
|
||||
|
||||
```text
|
||||
ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest
|
||||
```
|
||||
|
||||
- `host` — the job's steps run directly on the machine, with the tools installed there:
|
||||
|
||||
```text
|
||||
macos:host
|
||||
```
|
||||
|
||||
So a runner registered with
|
||||
The label name is the part before the first `:docker`, `:kubernetes` or `:host`. Workflows use this name in `runs-on`. For example:
|
||||
|
||||
```text
|
||||
ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest,macos:host
|
||||
```
|
||||
|
||||
runs `runs-on: ubuntu-latest` jobs in the `runner-images:ubuntu-latest` container and `runs-on: macos` jobs directly on the host.
|
||||
With these labels, `runs-on: ubuntu-latest` jobs run in a container. Jobs with `runs-on: macos` run on the runner's machine.
|
||||
|
||||
Names may themselves contain a colon, for example `pool:e57e18d4-10d4-406f-93bf-60f127221bdd`; only `host` and `docker` are treated as schemas.
|
||||
A job's `container:` image replaces the label's image. The job runs in a container even with a `host` label.
|
||||
|
||||
If a job's `runs-on` matches none of the runner's labels, the job still runs, in the default `docker.gitea.com/runner-images:ubuntu-latest` image. Images maintained for this purpose are listed at [gitea/runner-images](https://gitea.com/gitea/runner-images); community images such as the [act images](https://github.com/nektos/act/blob/master/IMAGES.md) work too.
|
||||
A job whose `runs-on` matches none of the runner's labels uses `runner.default_image`, which defaults to `docker.gitea.com/runner-images:ubuntu-latest`. It runs in a container, as a pod on runners with `kubernetes` but no `docker` labels, or on the host when no Docker daemon is reachable.
|
||||
|
||||
:::note
|
||||
A runner that only exposes `host` labels still needs access to a Docker daemon whenever a job uses a `docker://` action or a service container. `host` labels only change where the job's own steps run.
|
||||
:::
|
||||
## Changing labels
|
||||
|
||||
## Registration versus config labels
|
||||
Labels are set during registration and stored in the registration file. To change them, set them in the configuration file or on the command line, then restart the runner. The runner reports its labels to Gitea at startup:
|
||||
|
||||
Labels are chosen at registration time (`--labels`, or the interactive prompt) and stored in the registration file. Afterwards they can be changed without re-registering, and the most explicit source wins:
|
||||
|
||||
```text
|
||||
--labels / GITEA_RUNNER_LABELS > runner.labels in the config file > labels in the .runner file
|
||||
```bash
|
||||
gitea-runner config set runner.labels 'ubuntu-latest:docker://node:24' 'macos:host'
|
||||
```
|
||||
|
||||
- during `register`, `runner.labels` from the config file takes precedence and the `--labels` flag is ignored;
|
||||
- `daemon --labels` (which defaults to `GITEA_RUNNER_LABELS`) overrides the labels of an already registered runner;
|
||||
- whenever the resulting labels differ from those in the registration file, they are written back to it and re-declared to the instance on startup;
|
||||
- labels that fail to parse are skipped with a warning instead of stopping the runner.
|
||||
|
||||
Labels can also be edited in the Gitea UI under the runner's settings.
|
||||
`daemon --labels` or the `GITEA_RUNNER_LABELS` environment variable takes precedence over `runner.labels`. The `runner.labels` setting takes precedence over labels in the registration file.
|
||||
|
||||
## Choosing images
|
||||
|
||||
- Pick an image that already contains the tools your workflows expect. The default images are small; a job that installs a toolchain on every run is usually better served by a purpose-built image.
|
||||
- Pin images by tag or digest for reproducible jobs. An image pinned by digest is never re-pulled, even with `container.force_pull` enabled.
|
||||
- Use distinct names such as `linux_amd64:host` or `windows:host` for host labels, so a workflow written for GitHub's `ubuntu-latest` does not accidentally run unsandboxed on your machine.
|
||||
- Use the [runner images](https://gitea.com/gitea/runner-images) for tools that common workflows need. To avoid installing a toolchain on every run, choose an image that already includes it.
|
||||
- Pin images by tag or digest for reproducible jobs.
|
||||
- Give host labels distinct names such as `macos-arm64` to prevent workflows written for GitHub's `ubuntu-latest` from running directly on your machine without a sandbox.
|
||||
Reference in new issue
Block a user