Document runner 4 and 5, regenerate the 28.2.0 api documents (#599)

The 28.2.0 bump in #594 only changed the version string of the api documents, so they still listed the 28.1.0 endpoints. They are now regenerated from v28.2.0 (mostly new `423 repoArchivedError` responses).

The runner docs stopped at 3.3.0 while the runner is at 5.1.1:

- cut the runner `4` and `5` series, `/runner/` now serves 5.1.1 and `/runner/4/` 4.1.0, the `3` series is bumped to 3.5.0
- series specific image tags and versions in the new copies, the `3` series no longer claims the `latest` tag
- 4.0 and 5.0 sections in the upgrade guide, and the Git 2.34.1 requirement of 5.0 in the requirements
- regenerated every reference page from the newest stable tag of its series

Reviewed-on: https://gitea.com/gitea/docs/pulls/599
Reviewed-by: TheFox0x7 <[email protected]>

runner-docs/index.md

@@ -22,6 +22,8 @@ A runner needs a Gitea instance with Actions enabled, a [registration token](reg
 ENABLED=true
 ```
 
+The runner downloads actions and reusable workflows with Git, so it needs Git 2.34.1 or newer on its `PATH`; jobs that use `builtin:checkout` need Git in their image as well. The official runner images include it.
+
 Other OCI engines that implement the Docker API may work, but are untested. Podman is not a supported configuration.
 
 ## Execution modes
@@ -47,4 +49,4 @@ Every command and flag is listed in the [command line reference](reference/cli.m
 
 The runner is released independently of Gitea and its version numbers are unrelated to the instance's. Gitea 1.21 or later is expected — older instances cannot accept the runner's label declaration — and individual features need a newer instance still, which is called out where they apply.
 
-When moving between major runner versions, read [Upgrading](upgrade.md) first: `2.0.0` and `3.0.0` both contain breaking changes.
+When moving between major runner versions, read [Upgrading](upgrade.md) first: `2.0.0`, `3.0.0`, `4.0.0` and `5.0.0` all contain breaking changes.

runner-docs/upgrade.md

@@ -16,6 +16,41 @@ With `runner.shutdown_timeout` set, `stop` lets the jobs in flight finish first;
 
 Config files are read leniently: keys the running version does not know are reported as a warning and ignored, so one file can be shared by runners of different versions. Compare your file with `gitea-runner generate-config` after an upgrade to pick up new options.
 
+## 5.0
+
+### Breaking
+
+- **Git 2.34.1 or newer is required.** Actions and reusable workflows are downloaded with Git, so the runner needs `git` on its `PATH`. `builtin:checkout` runs Git inside the job too, so job images need Git, and the job must reach Gitea and trust its certificate. The official runner images include Git.
+- **`builtin:checkout` works like `actions/checkout`.** It removes untracked and ignored files from the checkout directory unless `clean: false` is set, and fails when the triggering tag was moved after the workflow started. In exchange it gains SSH keys, LFS, submodules, sparse checkout, partial clones, the `fetch-tags`, `clean`, `show-progress` and `set-safe-directory` inputs, and the `ref` and `commit` outputs.
+- **Config values expand `${NAME}`.** A value containing `${NAME}` reads that variable from the runner's environment, and the config fails to load when it is unset. Write `$${NAME}` to keep a literal `${NAME}`, for example in a shell command inside a Kubernetes `pod_template`.
+- **Jobs require `runs-on`.** A job without `runs-on`, or with an empty one, fails instead of running in `runner.default_image`, like on GitHub. Jobs that call a reusable workflow are exempt.
+- **Metrics follow the OpenTelemetry semantic conventions.** OTLP metric names, units, types and attributes change, see [docs/telemetry.md](https://gitea.com/gitea/runner/src/branch/main/docs/telemetry.md#metrics). On `/metrics`, `gitea_runner_client_errors_total` gains a `code` label, and `gitea_runner_job_total` counts jobs stopped by `runner.timeout` as `timeout`.
+- **Unprivileged runners ignore log and OOM options from workflows.** Unless `container.privileged` is set, `--log-driver`, `--log-opt`, `--oom-score-adj` and `--oom-kill-disable` are dropped from a job's `container.options` with a warning.
+
+### Also new
+
+- Mutual TLS to Gitea (`runner.client_cert_file`, `runner.client_key_file`) and `runner.extra_headers` for headers a reverse proxy in front of Gitea requires.
+- SHA-256 repositories for actions, reusable workflows and `builtin:checkout`.
+- `:ro` entries in `container.valid_volumes`, which only allow read-only mounts, and `container.sweep: false` to keep services that jobs deploy to the runner's Docker daemon.
+- The `gitea_runner_state` metric, reporting whether the runner is busy, idle or unavailable.
+- From `5.1`: action `pre` and `post` steps shown as their own steps on Gitea versions that support it, startup retried while Gitea is unreachable, and `runner.log_report_level` to set the level of runner messages in the job log independently of `log.level`.
+
+## 4.0
+
+### Breaking
+
+- **Jobs reach the cache through their runner.** With `cache.external_server` set, jobs send their cache requests to their runner, which forwards them; only the runner has to reach the external server, and that server no longer has to reach Gitea. Jobs that cannot reach their runner, such as on a remote `DOCKER_HOST`, need `cache.host` and `cache.port` set to an address they can reach.
+- **`container.network: bridge` cuts jobs off from a containerized runner.** Jobs on the default `bridge` network cannot reach a runner container outside it, so their cache and artifact uploads fail. Leave `container.network` empty or use a user-defined network.
+- **`*` in `container.valid_volumes` no longer matches across `/`.** A host pattern that relied on `*` matching nested paths needs `**`, for example `/data/**` instead of `/data/*`.
+
+### Also new
+
+- `builtin:checkout`, which needs neither a download nor Node in the job image, see [docs/builtin-actions.md](https://gitea.com/gitea/runner/src/branch/main/docs/builtin-actions.md), and the `self:` prefix for actions hosted on the runner's own instance.
+- S3-compatible storage as a cache backend (`cache.s3` in the [example configuration](reference/config-example.md)), shared between runners without a cache server.
+- [OpenTelemetry tracing](monitoring.md#opentelemetry-tracing) of jobs and steps, and from `4.1` the Prometheus metrics exported through OpenTelemetry as well.
+- A Kubernetes backend that runs jobs as pods (`4.1`), see [docs/kubernetes.md](https://gitea.com/gitea/runner/src/branch/main/docs/kubernetes.md).
+- A runner container on the jobs' Docker daemon joins every job network, so jobs reach its cache without `cache.host`, and `--umask` is accepted in `container.options`.
+
 ## 3.0
 
 ### Breaking