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]>

runner-docs_versioned_docs/version-5/registration.md

@@ -2,84 +2,54 @@
 sidebar_position: 2
 ---
 
-# Registering a runner
+# Registration
 
-A runner has to be registered before it can pick up jobs: registration is what tells the runner where to fetch jobs from, and what gives the Gitea instance a stable identity for the runner.
+Register a runner once with a Gitea instance to get its identity and credentials.
 
-## Obtain a registration token
+## Registration token
 
-Registration tokens are issued by the Gitea instance and can be scoped to the whole instance, an organization/user, or a single repository. See [Actions runners](/usage/actions/runner) for where to find them in the UI and via the API.
+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](/usage/actions/runner). A token can register any number of runners until it is reset.
 
-One token can register any number of runners and stays valid until it is reset in the UI or through the API. Instance administrators can also hand Gitea a fixed token with `GITEA_RUNNER_REGISTRATION_TOKEN` / `GITEA_RUNNER_REGISTRATION_TOKEN_FILE` at startup, which is what makes disposable runners practical.
-
-## Interactive registration
+## Registering
 
 ```bash
-gitea-runner register
-# or with a config file
-gitea-runner -c config.yaml register
+gitea-runner register --instance https://gitea.example.com --token <token>
 ```
 
-The runner asks for:
-
-- the instance URL, e.g. `https://gitea.com/` or `http://192.168.8.8:3000/` — use the instance's `ROOT_URL`, not `localhost`, when Gitea and the runner are in different containers or hosts;
-- the registration token;
-- the runner name, defaulting to the hostname;
-- the [labels](labels.md), defaulting to the built-in list, or to `runner.labels` when the config file sets it.
-
-## Non-interactive registration
+The runner asks for its name. It also asks for its [labels](labels.md) unless you set `runner.labels`. To skip the prompts, use `--no-interactive` and pass the values as flags:
 
 ```bash
 gitea-runner register --no-interactive \
-  --instance <instance_url> \
-  --token <registration_token> \
-  --name <runner_name> \
-  --labels <runner_labels>
+  --instance https://gitea.example.com \
+  --token <token> \
+  --name my-runner \
+  --labels ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest
 ```
 
-The token can be kept off the command line, where it would show up in the process list and in shell history:
+Set `--instance` to the instance's `ROOT_URL`. `localhost` does not work from job containers.
 
-- `--token-file <path>` reads it from a file, e.g. a Docker or Kubernetes secret;
-- the `GITEA_RUNNER_REGISTRATION_TOKEN` environment variable is used when neither flag is given.
+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
 
-A successful registration writes a `.runner` file (`runner.file` in the config) into the current working directory. It holds the runner's identity and its API credentials, so:
+Registration writes the runner's credentials to `.runner` in the working directory, or to the path in `runner.file`:
 
-- do not edit it by hand, and do not copy it to a second machine;
-- back it up or put it on a persistent volume, otherwise a recreated runner registers as a *new* runner and leaves a stale entry behind — and fails outright if the token has been reset in the meantime;
-- if it is lost or corrupted, delete it and register again.
-
-Each runner process needs its own registration file. Two processes sharing one file are indistinguishable to Gitea and cancel each other's jobs, so the runner takes an advisory lock on `<runner.file>.lock` and refuses to start when another process already holds it. The lock is released by the operating system when the process exits, including after a crash. When the lock cannot be created at all — for example on a read-only mount — the runner logs a warning and starts without the guard.
+- 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 and then exits. Once a job has been assigned, its credentials are revoked, so it cannot poll for more work before the job's untrusted code runs; it can still report progress until the job finishes.
-
-This is how organization-wide or instance-wide runners can be offered without trusting every repository that may use them, provided each runner is a fresh VM or container.
+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.
 
 ```bash
-gitea-runner register --ephemeral
-gitea-runner register --no-interactive --ephemeral --instance <instance_url> --token <registration_token>
+gitea-runner register --ephemeral --instance https://gitea.example.com --token <token>
 ```
 
-With the Docker images, set `GITEA_RUNNER_EPHEMERAL=1` instead; no `/data` volume is needed, since the credentials are single-use:
+With the Docker images, set `GITEA_RUNNER_EPHEMERAL=1`. To start a runner for each job, listen for Gitea's `workflow_job` [webhook](/usage/repository/webhooks), which fires when a job is queued.
 
-```bash
-docker run -d --name my_runner \
-  -e GITEA_INSTANCE_URL=<instance_url> \
-  -e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
-  -e GITEA_RUNNER_EPHEMERAL=1 \
-  -v /var/run/docker.sock:/var/run/docker.sock \
-  docker.io/gitea/runner:5
-```
+`gitea-runner daemon --once` also exits after one job, but its credentials stay valid.
 
-Because a fresh registration is required for every job, ephemeral runners are usually started on demand from the `workflow_job` webhook, which fires when a job is queued.
+## Removing a runner
 
-`--ephemeral` is stricter than `daemon --once`: `--once` also stops after one job, but its credentials stay valid for as long as the runner is registered.
-
-## Re-registering and unregistering
-
-Running `register` again in a directory that already has a registration file asks whether to overwrite it. To retire a runner, delete it in the Gitea UI (or via the API) and remove its registration file; the daemon shuts itself down once the server no longer knows it.
-
-Changing labels does not require re-registration — see [Labels](labels.md#registration-versus-config-labels).
+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.