nprasad2077/docs
1
1 Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-11-04 17:19:52 +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/proxy.md
+17 -21
View File
@@ -1,10 +1,10 @@
---
sidebar_position: 6
sidebar_position: 7
---
# Proxies
The runner reads the usual proxy variables from its own environment and passes them on to every job:
Set proxy variables in the runner's environment. Use `Environment=` in a systemd unit, `docker run -e`, or `env:` in Kubernetes:
```sh
http_proxy=http://proxy.example:3128
@@ -12,35 +12,31 @@ https_proxy=http://proxy.example:3128
no_proxy=gitea.internal,.example.local
```
Set them where the process is started — `Environment=` in a systemd unit, `docker run -e`, or `env:` in Kubernetes. They are used for the runner's own requests and are given to jobs in both lower and upper case.
The runner uses these variables for its own requests. It passes them to every job and service container in lowercase and uppercase. Dockerfile actions receive them as build arguments.
## What is exempted automatically
The runner adds the following to `no_proxy` so jobs reach them directly:
These are added to `no_proxy` for jobs, so they are always reached directly:
- the cache server
- The runner's cache server
- `localhost`, `127.0.0.1` and `::1`
- the job's service containers
- the Docker daemon, when it is reached over `tcp://`
- The job's service containers
- The Docker daemon, when reached over `tcp://`
The Gitea instance is **not** added. Add it to `no_proxy` yourself if it should be reached directly.
Add Gitea to `no_proxy` if jobs should reach it directly. The runner does not add it automatically.
## Overriding per job or per runner
## Changing the proxy for jobs
| Scope | Where to set it |
| --- | --- |
| one step | the step's `env:` |
| one job | the job's `container.env` |
| the whole runner | `runner.envs` in the config; a `no_proxy` set there is added to the list above instead of replacing it |
| One step | Set the step's `env:`. |
| The rest of a job | Write lowercase and uppercase variable names to `$GITHUB_ENV`. |
| Every job | Set `runner.envs`. Values in `no_proxy` are added to the list above. |
Setting proxy variables at workflow or job level (outside `container.env`) has no effect.
Proxy values set at the workflow or job level, or in `container.env`, cannot replace the runner's proxy values.
## The Docker daemon needs its own setting
## Docker daemon
Images are pulled by the daemon, not by the runner, so the daemon needs its own proxy configuration. In the `dind` images the daemon shares the container's environment and picks the variables up; for any other daemon see [the Docker documentation](https://docs.docker.com/engine/daemon/proxy/). The runner logs a warning at startup when it has a proxy configured and the daemon does not.
The Docker daemon pulls images and needs its own proxy settings. See [the Docker documentation](https://docs.docker.com/engine/daemon/proxy/). The Docker daemon bundled with the `dind` images reads the runner's proxy variables. The runner warns at startup if it has a proxy but the Docker daemon does not.
Dockerfile actions are built with these variables passed as build arguments, so their `RUN` steps can reach the network.
## Credentials
## Credentials in proxy URLs
A password inside a proxy URL is masked in job logs, but any step can still read it: the step is given the proxy URL in its environment. Prefer a proxy that does not need credentials, or one that authenticates by source address.
The runner masks passwords in proxy URLs in job logs, but every step can read them from its environment. Prefer a proxy that authenticates by source address.