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]>
2026-11-04 09:15:33 +00:00 · 2026-10-21 05:25:45 +00:00
parent a874918bb7
commit be6aefc7e8
53 changed files with 1531 additions and 1661 deletions
@@ -38,7 +38,7 @@ Use "gitea-runner [command] --help" for more information about a command.

 ## register

-Registers the runner against a Gitea instance and writes the registration file. Interactive unless `--no-interactive` is given; the token can also come from `--token-file` or the `GITEA_RUNNER_REGISTRATION_TOKEN` environment variable. See [Registering a runner](../registration.md).
+Registers the runner with a Gitea instance and writes the registration file. The token comes from `--token`, `--token-file` or the `GITEA_RUNNER_REGISTRATION_TOKEN` environment variable, and the command asks for the other settings unless `--no-interactive` is given. See [Registration](../registration.md).

 ```text
 Register a runner to the server
@@ -135,7 +135,7 @@ Global Flags:

 ## cache-server

-Runs only the cache server, so several runners can share one cache. `--dir`, `--host` and `--port` override the matching `cache.*` keys; every other setting, `cache.external_secret` included, has to come from the config file. See [Caching](../cache.md#sharing-a-cache-between-runners).
+Runs only the cache server, so several runners can share one cache. `--dir`, `--host` and `--port` override the matching `cache.*` keys. Every other setting, `cache.external_secret` included, has to come from the config file. See [Caching](../cache.md#sharing-a-cache-between-runners).

 ```text
 Start a cache server for the cache action
@@ -153,18 +153,121 @@ Global Flags:
  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable
 ```

-## generate-config
+## config

-Prints the commented example configuration on stdout, which is the starting point for a config file: `gitea-runner generate-config > config.yaml`.
+Writes, reads and edits config files. `config init` writes a minimal `config.yaml`, `config set`, `add` and `remove` change it in place, and `config generate` prints every option. See [Configuration](../configuration.md).
+
+```text
+Generate, read and edit config files
+
+Usage:
+  gitea-runner config [flags]
+  gitea-runner config [command]
+
+Available Commands:
+  add         Append values to a list config key
+  generate    Print the example config, which documents every option
+  get         Print the value of a config key
+  init        Write a minimal config file
+  remove      Remove values from a list config key
+  set         Set the value of a config key
+
+Flags:
+  -h, --help   help for config
+
+Global Flags:
+  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable
+
+Use "gitea-runner config [command] --help" for more information about a command.
+```
+
+### config add
+
+```text
+Append values to a list config key
+
+Usage:
+  gitea-runner config add <key> <value>... [flags]
+
+Flags:
+  -h, --help   help for add
+
+Global Flags:
+  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable
+```
+
+### config generate

 ```text
 Print the example config, which documents every option

 Usage:
-  gitea-runner generate-config [flags]
+  gitea-runner config generate [flags]

 Flags:
-  -h, --help   help for generate-config
+  -h, --help   help for generate
+
+Global Flags:
+  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable
+```
+
+### config get
+
+```text
+Print the value of a config key
+
+Usage:
+  gitea-runner config get <key> [flags]
+
+Flags:
+  -h, --help   help for get
+
+Global Flags:
+  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable
+```
+
+### config init
+
+```text
+Write a minimal config file, leaving every option at its default.
+Without --config it writes config.yaml in the working directory.
+
+Usage:
+  gitea-runner config init [flags]
+
+Flags:
+  -f, --force   overwrite an existing config file
+  -h, --help    help for init
+
+Global Flags:
+  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable
+```
+
+### config remove
+
+```text
+Remove values from a list config key
+
+Usage:
+  gitea-runner config remove <key> <value>... [flags]
+
+Flags:
+  -h, --help   help for remove
+
+Global Flags:
+  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable
+```
+
+### config set
+
+```text
+Set the value of a config key
+
+Usage:
+  gitea-runner config set <key> <value>... [flags]
+
+Flags:
+  -h, --help   help for set

 Global Flags:
  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable