Gitea Runner 5.0.0 is released

We are happy to announce the release of Gitea Runner 5.0.0.

This is a quiet major release. A handful of small breaking changes required the version bump, but most setups upgrade without changes. The main feature is a much more capable builtin:checkout.

Highlights in 5.0.0

builtin:checkout works like actions/checkout

In 4.0.0, builtin:checkout supported only a small subset of actions/checkout. It now runs git where the job runs and supports nearly all of it (#1277):

• SSH: ssh-key, ssh-known-hosts, ssh-strict, and ssh-user
• LFS and submodules: lfs: true, submodules: true or recursive
• Sparse checkout and partial clones: sparse-checkout, sparse-checkout-cone-mode, and filter, for example blob:none
• Other inputs: fetch-tags, clean, show-progress, persist-credentials, and set-safe-directory
• Outputs: ref and commit, as with actions/checkout

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: builtin:checkout
        with:
          lfs: true
          submodules: recursive
          fetch-depth: 0
      - run: make test

Branches are checked out as local branches tracking origin, so later steps can fetch and push with the persisted token or SSH key. Credentials are removed when the job ends.

See docs/builtin-actions.md for the full list of inputs.

The runner also downloads actions and reusable workflows with the Git CLI instead of go-git. This adds support for SHA-256 repositories and makes full action clones several times faster.

Smaller additions

• Mutual TLS: runner.client_cert_file and runner.client_key_file set a client certificate for connections to Gitea (#1273).
• Reverse proxy headers: runner.extra_headers adds headers that a proxy in front of Gitea requires (#1269).
• Environment variables in config: a config value can contain ${NAME}, which reads that variable from the runner’s environment (#1274).
• Read-only volumes: valid_volumes entries ending in :ro allow only read-only mounts (#1272).
• container.sweep: false: keeps services that jobs start on the runner’s Docker daemon after the job ends (#1275).
• gitea_runner_state metric: reports whether the runner is busy, idle, or unavailable (#1282).

Gitea Runner 4.1.0 added a Kubernetes backend that runs each job as a pod without a Docker daemon (#1260), and OTLP export of the Prometheus metrics (#1248).

Breaking changes

1. Git 2.34.1 or newer is required (#1277). The runner needs git on its PATH to download actions and reusable workflows. Job images that use builtin:checkout need it too, and those jobs must reach Gitea and trust its certificate. The gitea/runner images include Git.

2. builtin:checkout cleans the checkout and checks tags (#1277). As with actions/checkout, untracked and ignored files are removed from the checkout directory unless clean: false is set. The step also fails when the triggering tag was moved after the workflow started.

3. Config values expand ${NAME} (#1274). If a config value contains ${NAME} and that variable is unset, the config fails to load. To keep a literal ${NAME}, such as in a shell command inside a Kubernetes pod_template, write $${NAME}.

4. Jobs require runs-on (#1271). A workflow with a job that has no runs-on, or an empty one, now fails instead of running that job in runner.default_image. This matches GitHub. Jobs that call a reusable workflow are exempt.

5. Metrics follow the OpenTelemetry semantic conventions (#1282). OTLP metric names, units, types, and attributes have changed. See the metrics docs. On the Prometheus /metrics endpoint, gitea_runner_client_errors_total has a new code label, and gitea_runner_job_total counts jobs stopped by runner.timeout as timeout.

6. Unprivileged runners ignore workflow log and OOM options (#1283). Unless container.privileged is set, the runner drops --log-driver, --log-opt, --oom-score-adj, and --oom-kill-disable from a workflow’s container options and logs a warning.

Upgrade notes

• Replace gitea/runner:4.x with gitea/runner:5.0.0 in Docker Compose, Kubernetes manifests, and service units.
• If you run the binary directly, make sure Git 2.34.1 or newer is installed on the host. Make sure job images that use builtin:checkout include Git as well.
• Search your config for literal ${ and escape it as $${ where it should not be expanded.
• Add runs-on to any job that relied on runner.default_image without one.
• If you build dashboards or alerts on the OTLP metrics, update them for the new names.

Download

Pre-built binaries are available from the Gitea Runner downloads page.

The release is also available from the Gitea Runner release page.

Thank you

Thank you to everyone who contributed code, testing, bug reports, documentation, and feedback since the 4.0.0 release.

---

Changelog

5.0.0 - 2026-10-08

• BREAKING

  • Use the Git CLI for action clones and make builtin:checkout match actions/checkout, requiring Git 2.34.1 or newer (#1277)
  • Expand ${NAME} in config values (#1274)
  • Reject workflows with jobs lacking runs-on (#1271)
  • Send OTLP metrics under the OpenTelemetry semantic conventions (#1282)
  • Strip log-driver and OOM options when privileged is off (#1283)

• FEATURES

  • Support SSH keys, LFS, submodules, sparse checkout, and partial clones in builtin:checkout (#1277)
  • Support SHA-256 repositories for actions, reusable workflows, and builtin:checkout (#1277)
  • Support client certificates for mutual TLS (#1273)
  • Add runner.extra_headers (#1269)
  • Support :ro entries in valid_volumes (#1272)
  • Add container.sweep option (#1275)
  • Add gitea_runner_state metric (#1282)

• BUGFIXES

  • Recognize Gitea’s 401 reply for an unregistered runner, fixing ephemeral runner restarts (#1287)
  • Extract copied directories at their destination in Kubernetes pods (#1286)
  • Allow tmpfs mounts in container options (#1289)
  • Match matrix include and exclude entries regardless of case (#1278)
  • Apply runner.insecure to reusable workflow downloads and job summary uploads (#1273)
  • Apply the Docker daemon’s mtu to job networks (#1270)

4.1.0 - 2026-10-01

• FEATURES

  • Add a Kubernetes backend for running jobs (#1260)
  • Export the Prometheus metrics over OpenTelemetry (#1248)
  • Log task, job, and run identifiers when a task starts (#1257)

• BUGFIXES

  • Align Docker actions, job env, and host mode with GitHub (#1268)
  • Drop stalled HTTP/2 connections in action clones (#1266)
  • Fail fast in register and honor GITEA_MAX_REG_ATTEMPTS (#1197)
  • Fix dind image readiness, exit codes, and shutdown order (#1265)
  • Clear consumed ephemeral registration state (#1256)

4.0.1 - 2026-09-29

• BUGFIXES
  • Resolve container sleep through PATH (#1255)
  • Honor the configured Docker registration file (#1259)
  • Apply a job container without image to the runs-on image (#1252)
  • Restore the caller’s event and inputs in reusable workflow jobs (#1250)
  • Miscellaneous bug fixes and improvements (#1253)