silverwind
be6aefc7e8
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]>
2.4 KiB
sidebar_position
| sidebar_position |
|---|
| 2 |
Registration
Register a runner once with a Gitea instance to get its identity and credentials.
Registration token
Gitea issues registration tokens for the whole instance, an organization, a user, or a single repository. A runner accepts jobs within the token's scope. To find a token, see Gitea Runner. A token can register any number of runners until it is reset.
Registering
gitea-runner register --instance https://gitea.example.com --token <token>
The runner asks for its name. It also asks for its labels unless you set runner.labels. To skip the prompts, use --no-interactive and pass the values as flags:
gitea-runner register --no-interactive \
--instance https://gitea.example.com \
--token <token> \
--name my-runner \
--labels ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest
Set --instance to the instance's ROOT_URL. localhost does not work from job containers.
To keep the token out of shell history and the process list, pass it with --token-file <path> or through the GITEA_RUNNER_REGISTRATION_TOKEN environment variable.
The registration file
Registration writes the runner's credentials to .runner in the working directory, or to the path in runner.file:
- Keep it on persistent storage. If the file is lost, register again as a new runner.
- Give each runner process its own registration file. A second process using the same file refuses to start.
- Treat it as a secret.
Ephemeral runners
An ephemeral runner accepts exactly one job, then exits. Its credentials are revoked as soon as the job is assigned, so the job cannot use them to accept more work. Start each ephemeral runner in a fresh VM or container when running jobs from repositories you do not fully trust.
gitea-runner register --ephemeral --instance https://gitea.example.com --token <token>
With the Docker images, set GITEA_RUNNER_EPHEMERAL=1. To start a runner for each job, listen for Gitea's workflow_job webhook, which fires when a job is queued.
gitea-runner daemon --once also exits after one job, but its credentials stay valid.
Removing a runner
Delete the runner in Gitea's runner settings, then delete its registration file. The runner exits when it detects that Gitea has removed its registration.