Renovate Bot 891f3fde38 fix(deps): update dependencies (#1414)
This PR contains the following updates:

| Package | Type | Update | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) |
|---|---|---|---|---|---|
| docker.gitea.com/runner-images |  | digest | `b96ba46` → `139605d` |  |  |
| [docker/login-action](https://github.com/docker/login-action) ([changelog](https://github.com/docker/login-action/compare/81c6f93d4bc991e510b342a00b419b3bb4efc5c6..8aa5831fb8d48d8f76594c7ddde61ae58019f550)) | action | digest | `81c6f93` → `8aa5831` |  |  |
| [github.com/spf13/pflag](https://github.com/spf13/pflag) | require | minor | `v1.0.10` → `v1.1.0` | ![age](https://developer.mend.io/api/mc/badges/age/go/github.com%2fspf13%2fpflag/v1.1.0?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/go/github.com%2fspf13%2fpflag/v1.0.10/v1.1.0?slim=true) |
| [go](https://go.dev/) ([source](https://github.com/golang/go)) | toolchain | patch | `1.27.3` → `1.27.4` | ![age](https://developer.mend.io/api/mc/badges/age/golang-version/go/1.27.4?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/golang-version/go/1.27.3/1.27.4?slim=true) |
| [golang.org/x/sync](https://pkg.go.dev/golang.org/x/sync) | require | minor | [`v0.24.0` → `v0.25.0`](https://cs.opensource.google/go/x/sync/+/refs/tags/v0.24.0...refs/tags/v0.25.0) | ![age](https://developer.mend.io/api/mc/badges/age/go/golang.org%2fx%2fsync/v0.25.0?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/go/golang.org%2fx%2fsync/v0.24.0/v0.25.0?slim=true) |
| [golang.org/x/sys](https://pkg.go.dev/golang.org/x/sys) | require | minor | [`v0.49.0` → `v0.50.0`](https://cs.opensource.google/go/x/sys/+/refs/tags/v0.49.0...refs/tags/v0.50.0) | ![age](https://developer.mend.io/api/mc/badges/age/go/golang.org%2fx%2fsys/v0.50.0?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/go/golang.org%2fx%2fsys/v0.49.0/v0.50.0?slim=true) |
| [golang.org/x/term](https://pkg.go.dev/golang.org/x/term) | require | minor | [`v0.47.0` → `v0.48.0`](https://cs.opensource.google/go/x/term/+/refs/tags/v0.47.0...refs/tags/v0.48.0) | ![age](https://developer.mend.io/api/mc/badges/age/go/golang.org%2fx%2fterm/v0.48.0?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/go/golang.org%2fx%2fterm/v0.47.0/v0.48.0?slim=true) |
| [golang.org/x/text](https://pkg.go.dev/golang.org/x/text) | require | minor | [`v0.43.0` → `v0.44.0`](https://cs.opensource.google/go/x/text/+/refs/tags/v0.43.0...refs/tags/v0.44.0) | ![age](https://developer.mend.io/api/mc/badges/age/go/golang.org%2fx%2ftext/v0.44.0?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/go/golang.org%2fx%2ftext/v0.43.0/v0.44.0?slim=true) |
| [quay.io/containers/podman](https://quay.io/containers/podman) ([source](https://github.com/podman-container-tools/podman)) |  | major | `v5.8.9-immutable` → `v6.1.3-immutable` | ![age](https://developer.mend.io/api/mc/badges/age/docker/quay.io%2fcontainers%2fpodman/v6.1.3?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/docker/quay.io%2fcontainers%2fpodman/v5.8.9/v6.1.3?slim=true) |

---

### HTTP/1 server crash due to MaxBytesReader header race in net/http
[CVE-2026-97054](https://nvd.nist.gov/vuln/detail/CVE-2026-97054) / [GO-2026-6859](https://pkg.go.dev/vuln/GO-2026-6859)

<details>
<summary>More information</summary>

#### Details
For HTTP/1 servers, when MaxBytesReader's limit is exceeded, "Connection: close" header is automatically set without synchronization, which might race with another header being set explicitly in the server handler. As a result, an HTTP/1 server that utilizes MaxBytesReader or MaxBytesHandler can crash due to runtime panic if its handler reads the request body concurrently with writing the response header.

#### Severity
Unknown

#### References
- [https://go.dev/cl/862185](https://go.dev/cl/862185)
- [https://go.dev/issue/82563](https://go.dev/issue/82563)
- [https://groups.google.com/g/golang-announce/c/iY8TY0wWgbM](https://groups.google.com/g/golang-announce/c/iY8TY0wWgbM)

This data is provided by [OSV](https://osv.dev/vulnerability/GO-2026-6859) and the [Go Vulnerability Database](https://github.com/golang/vulndb) ([CC-BY 4.0](https://github.com/golang/vulndb#license)).
</details>

---

### Release Notes

<details>
<summary>spf13/pflag (github.com/spf13/pflag)</summary>

### [`v1.1.0`](https://github.com/spf13/pflag/releases/tag/v1.1.0)

[Compare Source](https://github.com/spf13/pflag/compare/v1.0.10...v1.1.0)

It's been long enough, and enough things have been fixed, that it might be time to release a new version, even if there isn't any particular big new issue to market as the reason for this release.

If you notice anything breaking, it is entirely un-intentional, but you might also have been relying on [undocumented](https://www.hyrumslaw.com/) or [buggy](https://xkcd.com/1172/) behavior. Please file an issue describing what you're doing, how it worked before this release and why it doesn't work anymore, and pin your projects to `v1.0.10` (the latest release before this one) while we decide how to address your concerns.

#### What's Changed

- README: update badges and minor linting fixes by [@&#8203;thaJeztah](https://github.com/thaJeztah) in [#&#8203;452](https://github.com/spf13/pflag/pull/452)
- Show 'correct' explicit bool value syntax in help by [@&#8203;alimpfard](https://github.com/alimpfard) in [#&#8203;453](https://github.com/spf13/pflag/pull/453)
- Fix for Go 1.24 by [@&#8203;pterjan](https://github.com/pterjan) in [#&#8203;460](https://github.com/spf13/pflag/pull/460)
- fix(map): ensure string-to-string flags maintain stable pointers by [@&#8203;brandon1024](https://github.com/brandon1024) in [#&#8203;457](https://github.com/spf13/pflag/pull/457)
- Fix getFlagType error message by [@&#8203;wellitonscheer](https://github.com/wellitonscheer) in [#&#8203;462](https://github.com/spf13/pflag/pull/462)
- update actions, and fix linting issues by [@&#8203;thaJeztah](https://github.com/thaJeztah) in [#&#8203;450](https://github.com/spf13/pflag/pull/450)
- fix: README.md indicating the use of godoc(deprecated) by [@&#8203;malklera](https://github.com/malklera) in [#&#8203;467](https://github.com/spf13/pflag/pull/467)
- Fix broken link to POSIX argument conventions by [@&#8203;tomasaschan](https://github.com/tomasaschan) in [#&#8203;464](https://github.com/spf13/pflag/pull/464)
- Replace raw stdlib parse errors in typed flag Set methods ([#&#8203;269](https://github.com/spf13/pflag/issues/269)) by [@&#8203;reuvenharrison](https://github.com/reuvenharrison) in [#&#8203;469](https://github.com/spf13/pflag/pull/469)
- Extend `UnknownFlags` to `UnknownFlagsHandling` and introduce `PassUnknownFlagToArgs` ([#&#8203;337](https://github.com/spf13/pflag/issues/337)) by [@&#8203;ikedam](https://github.com/ikedam) in [#&#8203;440](https://github.com/spf13/pflag/pull/440)
- fix: allow nil default IP flags in GetIP by [@&#8203;happysnaker](https://github.com/happysnaker) in [#&#8203;483](https://github.com/spf13/pflag/pull/483)
- fix: allow hex input in UintSlice by [@&#8203;happysnaker](https://github.com/happysnaker) in [#&#8203;484](https://github.com/spf13/pflag/pull/484)
- fix: honor custom IsBoolFlag compatibility by [@&#8203;happysnaker](https://github.com/happysnaker) in [#&#8203;487](https://github.com/spf13/pflag/pull/487)
- docs: clarify SortFlags example with complete runnable program by [@&#8203;happysnaker](https://github.com/happysnaker) in [#&#8203;488](https://github.com/spf13/pflag/pull/488)
- docs: add release process documentation by [@&#8203;happysnaker](https://github.com/happysnaker) in [#&#8203;490](https://github.com/spf13/pflag/pull/490)
- fix: print to set destination, not hardcoded os.Stderr by [@&#8203;quite](https://github.com/quite) in [#&#8203;502](https://github.com/spf13/pflag/pull/502)
- ci: bump golangci-lint to v2.13 for Go 1.27 by [@&#8203;hdimer](https://github.com/hdimer) in [#&#8203;508](https://github.com/spf13/pflag/pull/508)
- Initialize the target map when a StringToString flag has a nil default by [@&#8203;nikolauspschuetz](https://github.com/nikolauspschuetz) in [#&#8203;506](https://github.com/spf13/pflag/pull/506)
- fix: honour deprecated ParseErrorsWhitelist.UnknownFlagsHandling by [@&#8203;lenamonj](https://github.com/lenamonj) in [#&#8203;507](https://github.com/spf13/pflag/pull/507)
- test: add StringSlice Append coverage by [@&#8203;LY-19418](https://github.com/LY-19418) in [#&#8203;504](https://github.com/spf13/pflag/pull/504)
- Keep wrapping after an unbreakable usage word by [@&#8203;AzazelSensei](https://github.com/AzazelSensei) in [#&#8203;503](https://github.com/spf13/pflag/pull/503)
- Validate IP slice values before appending or replacing by [@&#8203;agammann](https://github.com/agammann) in [#&#8203;513](https://github.com/spf13/pflag/pull/513)
- fix(ci): Use the latest golangci-lint release by [@&#8203;tomasaschan](https://github.com/tomasaschan) in [#&#8203;525](https://github.com/spf13/pflag/pull/525)
- Reject IPv6 addresses as IPv4 masks by [@&#8203;yuefdev](https://github.com/yuefdev) in [#&#8203;524](https://github.com/spf13/pflag/pull/524)
- Report the flag name as typed in deprecation warnings by [@&#8203;hdimer](https://github.com/hdimer) in [#&#8203;500](https://github.com/spf13/pflag/pull/500)
- Document non-interspersed argument parsing by [@&#8203;yuefdev](https://github.com/yuefdev) in [#&#8203;523](https://github.com/spf13/pflag/pull/523)
- Preserve trailing whitespace in StringToString formatting by [@&#8203;r4venrudy](https://github.com/r4venrudy) in [#&#8203;522](https://github.com/spf13/pflag/pull/522)
- Reject extra CSV records in StringToString arguments by [@&#8203;Harshil-1603](https://github.com/Harshil-1603) in [#&#8203;521](https://github.com/spf13/pflag/pull/521)
- Preserve current string values in CopyToGoFlagSet by [@&#8203;adenzhou1350](https://github.com/adenzhou1350) in [#&#8203;520](https://github.com/spf13/pflag/pull/520)
- Fix type identification and mismatch checks for text flags by [@&#8203;dewanshshekhar](https://github.com/dewanshshekhar) in [#&#8203;526](https://github.com/spf13/pflag/pull/526)
- fix: enforce native integer flag bounds on 32-bit platforms by [@&#8203;gdpu11](https://github.com/gdpu11) in [#&#8203;534](https://github.com/spf13/pflag/pull/534)
- fix: preserve count flag values when parsing fails by [@&#8203;gdpu11](https://github.com/gdpu11) in [#&#8203;533](https://github.com/spf13/pflag/pull/533)

#### New Contributors

- [@&#8203;alimpfard](https://github.com/alimpfard) made their first contribution in [#&#8203;453](https://github.com/spf13/pflag/pull/453)
- [@&#8203;pterjan](https://github.com/pterjan) made their first contribution in [#&#8203;460](https://github.com/spf13/pflag/pull/460)
- [@&#8203;brandon1024](https://github.com/brandon1024) made their first contribution in [#&#8203;457](https://github.com/spf13/pflag/pull/457)
- [@&#8203;wellitonscheer](https://github.com/wellitonscheer) made their first contribution in [#&#8203;462](https://github.com/spf13/pflag/pull/462)
- [@&#8203;malklera](https://github.com/malklera) made their first contribution in [#&#8203;467](https://github.com/spf13/pflag/pull/467)
- [@&#8203;reuvenharrison](https://github.com/reuvenharrison) made their first contribution in [#&#8203;469](https://github.com/spf13/pflag/pull/469)
- [@&#8203;ikedam](https://github.com/ikedam) made their first contribution in [#&#8203;440](https://github.com/spf13/pflag/pull/440)
- [@&#8203;happysnaker](https://github.com/happysnaker) made their first contribution in [#&#8203;483](https://github.com/spf13/pflag/pull/483)
- [@&#8203;quite](https://github.com/quite) made their first contribution in [#&#8203;502](https://github.com/spf13/pflag/pull/502)
- [@&#8203;hdimer](https://github.com/hdimer) made their first contribution in [#&#8203;508](https://github.com/spf13/pflag/pull/508)
- [@&#8203;nikolauspschuetz](https://github.com/nikolauspschuetz) made their first contribution in [#&#8203;506](https://github.com/spf13/pflag/pull/506)
- [@&#8203;lenamonj](https://github.com/lenamonj) made their first contribution in [#&#8203;507](https://github.com/spf13/pflag/pull/507)
- [@&#8203;LY-19418](https://github.com/LY-19418) made their first contribution in [#&#8203;504](https://github.com/spf13/pflag/pull/504)
- [@&#8203;AzazelSensei](https://github.com/AzazelSensei) made their first contribution in [#&#8203;503](https://github.com/spf13/pflag/pull/503)
- [@&#8203;agammann](https://github.com/agammann) made their first contribution in [#&#8203;513](https://github.com/spf13/pflag/pull/513)
- [@&#8203;yuefdev](https://github.com/yuefdev) made their first contribution in [#&#8203;524](https://github.com/spf13/pflag/pull/524)
- [@&#8203;r4venrudy](https://github.com/r4venrudy) made their first contribution in [#&#8203;522](https://github.com/spf13/pflag/pull/522)
- [@&#8203;Harshil-1603](https://github.com/Harshil-1603) made their first contribution in [#&#8203;521](https://github.com/spf13/pflag/pull/521)
- [@&#8203;adenzhou1350](https://github.com/adenzhou1350) made their first contribution in [#&#8203;520](https://github.com/spf13/pflag/pull/520)
- [@&#8203;dewanshshekhar](https://github.com/dewanshshekhar) made their first contribution in [#&#8203;526](https://github.com/spf13/pflag/pull/526)
- [@&#8203;gdpu11](https://github.com/gdpu11) made their first contribution in [#&#8203;534](https://github.com/spf13/pflag/pull/534)

**Full Changelog**: <https://github.com/spf13/pflag/compare/v1.0.10...v1.1.0>

</details>

<details>
<summary>podman-container-tools/podman (quay.io/containers/podman)</summary>

### [`v6.1.3`](https://github.com/podman-container-tools/podman/releases/tag/v6.1.3)

[Compare Source](https://github.com/podman-container-tools/podman/compare/v5.8.9...v6.1.3)

##### Security

- This release addresses [CVE-2026-94603](https://github.com/podman-container-tools/podman/security/advisories/GHSA-2cvf-wqm6-wr9g), where a `podman run` on a checkpoint image (any image with the `io.podman.annotations.checkpoint.runtime.name` annotation) could disable all sandboxing, including sandboxing specified by the user, when the container was created.

##### Breaking Changes

- Removed support for checkpoint images in `podman run` due to serious security concerns with the different security models of running images and running checkpoints. Checkpoints ignore user-specified security configuration and are very difficult to run safely.

</details>

---

### Configuration

📅 **Schedule**: (UTC)

- Branch creation
  - Between 12:00 AM and 03:59 AM, only on Monday (`* 0-3 * * 1`)
- Automerge
  - At any time (no schedule defined)

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

👻 **Immortal**: This PR will be recreated if closed unmerged. Get [config help](https://github.com/renovatebot/renovate/discussions) if that's undesired.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box

---

This PR has been generated by [Mend Renovate CLI](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0NC4yMjIuNSIsInVwZGF0ZWRJblZlciI6IjQ0LjIzOS4xIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6W119-->

Reviewed-on: https://gitea.com/gitea/runner/pulls/1414
Reviewed-by: silverwind <[email protected]>
Co-authored-by: Renovate Bot <[email protected]>
2026-11-16 15:15:09 +00:00
2023-03-18 01:58:21 -04:00
2026-11-16 15:15:09 +00:00
2026-11-16 15:15:09 +00:00
2022-11-24 15:36:16 +08:00
2026-08-06 21:50:21 +00:00

Gitea Runner

Gitea Runner runs the jobs of Gitea Actions workflows. Register it with a Gitea instance to run jobs in Docker containers, Kubernetes pods or directly on the host.

Installation

Prerequisites

  • Linux, macOS or Windows, or FreeBSD.
  • Gitea 1.26.2 or newer.
  • git 2.34.1 or newer.
  • docker, or podman with podman.socket enabled, for docker labels and Docker actions. See Docker's install instructions.

In the job image, or on the host for host jobs:

  • bash or sh, or pwsh or powershell on Windows.
  • node for JavaScript actions and hashFiles().

Kubernetes mode needs a few more tools in job images.

Download pre-built binary

Download the binary for your platform from dl.gitea.com.

Build from source

make build

Build a docker image

make docker

Quickstart

Enable Actions in the configuration file of your Gitea instance:

[actions]
ENABLED=true

Register

./gitea-runner register

It asks for:

  1. The Gitea instance URL. Use its ROOT_URL, not localhost or 127.0.0.1.
  2. A runner token, from /admin/actions/runners on your instance.
  3. A runner name, the hostname when left blank.
  4. The runner labels, the defaults when left blank.

To register without prompts:

./gitea-runner register --instance https://gitea.example.com --token <token> --no-interactive

Run

./gitea-runner daemon

Deployment

Windows service

Register the runner first, keeping gitea-runner.exe, config.yaml and the .runner file in one directory. Then install and start the service from an elevated Command Prompt:

sc.exe create gitea-runner binPath= "\"C:\gitea-runner\gitea-runner.exe\" daemon --config \"C:\gitea-runner\config.yaml\"" start= auto
sc.exe start gitea-runner

The service logs to gitea-runner.log next to the executable. Its account needs write access to that directory and access to the tools jobs use.

sc.exe stop gitea-runner lets running jobs finish within runner.shutdown_timeout. To allow the same on shutdown, raise the service's preshutdown timeout above it, here to six minutes. This takes effect after the next reboot:

reg.exe add HKLM\SYSTEM\CurrentControlSet\Services\gitea-runner /v PreshutdownTimeout /t REG_DWORD /d 360000 /f

Run with docker

The recommended Docker-in-Docker image runs its own Docker daemon for jobs. Jobs never get the host's Docker socket, which is equivalent to root access on the host.

docker run --privileged -e GITEA_INSTANCE_URL=https://your_gitea.com -e GITEA_RUNNER_REGISTRATION_TOKEN=<your_token> \
  -v "$PWD/data:/data" -v runner-docker:/var/lib/docker --name my_runner gitea/runner:latest-dind

The volumes keep the registration and the image cache across container recreation. The image reads more variables, such as GITEA_RUNNER_LABELS and CONFIG_FILE, see scripts/run.sh and the Docker example.

Image flavours

Tag Docker daemon for jobs
latest-dind (recommended) Bundled, needs --privileged.
latest-dind-rootless Bundled, runs as UID 1000 for stronger isolation. Needs --privileged and rootless Docker support on the host. Its image cache is in /home/rootless/.local/share/docker.
latest None. Mount the host's /var/run/docker.sock, or set DOCKER_HOST.

Versioned and nightly tags take the same suffixes, like nightly-dind. The images target Docker, not Podman.

Example deployments

See the examples directory for more deployments, among them systemd, launchd on macOS, Kubernetes and VMs.

Configuration

The runner reads an optional YAML file:

./gitea-runner config init             # write config.yaml, with no option set
./gitea-runner config generate | less  # read what the options do
./gitea-runner -c config.yaml daemon   # -c also works on register and cache-server

config generate prints config.example.yaml, which documents every option. Copy the lines you need into your file and uncomment them.

Editing a config file

config edits a file in place and keeps its comments, which suits provisioning scripts:

./gitea-runner config set runner.capacity 4
./gitea-runner config set runner.envs.MY_VAR value
./gitea-runner config add runner.labels 'ubuntu:docker://node:22'
./gitea-runner config remove runner.labels 'ubuntu:docker://node:22'
./gitea-runner config get runner.labels

Keys are dotted YAML paths. Unknown keys and invalid values are refused without touching the file. Without -c, it uses config.yaml from the working directory, then from the binary's directory.

Environment variables

Config values can read the runner's environment as ${NAME}, for example capacity: ${RUNNER_CAPACITY}. An unset variable fails the load, and $${NAME} stays a literal ${NAME}.

The override variables of earlier releases, such as GITEA_RUNNER_CAPACITY, are gone. Set those options in the file instead.

Labels

Labels decide which jobs a runner accepts and how it runs them. A job's runs-on is matched against the label names, and the first match picks where it runs.

A label is written as <name>[:<schema>[:<args>]], with one of these schemas:

  • docker://<image> runs the job in a container of <image>.
  • kubernetes://<image> runs it as a Kubernetes pod, see docs/kubernetes.md.
  • host, the default, runs its steps directly on the runner's machine.

With these labels, runs-on: ubuntu-latest runs in a container and runs-on: macos on the host:

ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest,macos:host

gitea/runner-images has suitable images. Jobs matching no label run in runner.default_image, or on the host when docker is unavailable.

Host jobs still need a Docker daemon for Docker actions and docker:// steps. Windows hosts do not support those, as on GitHub. A step's background processes end with the job unless it opts out, see host mode.

Registration vs config labels

Labels are set at registration, with --labels or the prompt. To change them later, use one of these, the leftmost set one wins:

daemon --labels / GITEA_RUNNER_LABELS   >   runner.labels in the config file   >   labels in the .runner file

Changed labels are saved to the .runner file and sent to Gitea on startup. When runner.labels is set, register uses it and ignores --labels.

Tool cache

Setup actions like setup-go install tools into RUNNER_TOOL_CACHE. runner.tool_cache_mode selects what backs it:

Mode Tool cache
none (default) Provided by the job image. Versions it lacks are downloaded in every job.
shared One volume per runner.capacity slot, reused by later jobs. It hides the tools later job images ship, so use images without them.

To ship tools in a job image, install them to /opt/hostedtoolcache/<tool>/<version>/<arch> with an empty <arch>.complete file next to it, as the -full runner images do:

RUN GO=$(curl -fsSL 'https://go.dev/dl/?mode=json' | grep -oP '"version": "\Kgo1\.26\.[0-9]*' | head -1); \
  DIR="/opt/hostedtoolcache/go/${GO#go}/x64" && \
  mkdir -p "$(dirname "$DIR")" && \
  curl -fsSL "https://dl.google.com/go/${GO}.linux-amd64.tar.gz" | tar -xz -C /tmp && \
  mv /tmp/go "$DIR" && \
  touch "${DIR}.complete"

Proxy

Set the proxy in the runner's environment, for example with systemd Environment= or docker run -e:

http_proxy=http://proxy.example:3128
https_proxy=http://proxy.example:3128
no_proxy=gitea.internal,.example.local

The runner uses it and passes it on to jobs. Jobs always reach the cache server, localhost, their service containers and a tcp:// Docker daemon directly. Add Gitea to no_proxy if it should be reached directly too.

To change the proxy for jobs, use runner.envs, a step's env: or $GITHUB_ENV. Workflow and job level env: have no effect on it.

The Docker daemon pulls images with its own proxy settings. The dind images pass the variables above to it, for other daemons see the Docker documentation.

A password in the proxy URL is hidden in logs, but every step can read it.

Jobs

Service containers

When a service declares a healthcheck, in its image or options, the job waits for it to become healthy:

services:
  postgres:
    image: postgres:18
    options: >-
      --health-cmd pg_isready
      --health-interval 5s
      --health-retries 10

A service that turns unhealthy, or is not healthy within container.service_ready_timeout, fails the job. Steps reach a service by its id and port, like psql -h postgres -p 5432.

Unlike GitHub, jobs running on the host start no services. Give them a container: to use services.

Docker from a job (GITEA_DOCKER_WORKSPACE)

Containers a job starts can bind-mount the workspace by its path, like docker run -v "$PWD:/src". Where the Docker daemon sees another path, for example a remote DOCKER_HOST, prefix the bind with GITEA_DOCKER_WORKSPACE:

volumes:
  - ${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data

Set container.sweep: true to remove the containers, networks and volumes most Linux container jobs create when they end, docker compose services included. Leave it off if jobs deploy services to the runner's Docker daemon.

Caching (actions/cache)

Each runner runs its own cache server. As on GitHub, a job restores caches of its own ref, its pull request's base branch and the default branch.

Sharing a cache between runners

Run one gitea-runner cache-server and point every runner at it with the same secret, for example from openssl rand -hex 32:

# cache-server.yaml
cache:
  dir: /data/actcache
  port: 8088
  external_secret: "<secret>" # or external_secret_file: /path/to/secret
gitea-runner -c cache-server.yaml cache-server
# each runner's config
cache:
  external_server: "http://<cache-server-host>:8088/"
  external_secret: "<secret>"

Runners can also share one cache.dir on a file system with working file locks, at the cost of slower requests.

Storing the cache in an S3-compatible bucket

Runners can share a cache in an S3-compatible bucket, such as AWS S3, MinIO or RustFS, without a cache server:

cache:
  s3:
    endpoint: "http://minio:9000"
    region: "us-east-1"
    bucket: "runner-cache"
    prefix: "gitea-runner-cache"
    path_style: true
    access_key_file: "/run/secrets/cache-s3-access-key"
    secret_key_file: "/run/secrets/cache-s3-secret-key"

Eviction does not apply to the bucket. Add lifecycle rules that expire old caches and abort incomplete multipart uploads.

Eviction

Entries unused for cache.retention (default 168h) are removed. A repository over cache.repo_size_limit (default 10GB) loses its least recently used entries. See config.example.yaml for more limits.

Cache service v2

The runner serves the cache service v2 API used by current actions/cache releases. It patches them to use it on Gitea, which also makes the stock actions/upload-artifact and actions/download-artifact v4 work. Artifact calls then go through the cache server, so jobs must be able to reach it.

Job hooks (runner.hooks.job_started, runner.hooks.job_completed)

Hook scripts run where the job's steps run, before the first step and after the last. They match GitHub's ACTIONS_RUNNER_HOOK_JOB_STARTED and ACTIONS_RUNNER_HOOK_JOB_COMPLETED.

Use them for per-job setup no workflow should carry, like registry logins or masking runner-wide secrets. They block the job, and a non-zero exit fails it. See docs/job-hooks.md.

Secret masking

Secrets and ::add-mask:: values are hidden in job logs, local job logs, job summaries and container names. As on GitHub, a job output containing one is dropped with a warning.

Operation

Idle cleanup

While idle, the runner removes leftovers of earlier jobs every runner.idle_cleanup_interval (default 10m):

  • Workspaces older than runner.workdir_cleanup_age (default 24h), when container.bind_workdir is on. This assumes no other runner shares container.workdir_parent.
  • Unused Docker networks and volumes of jobs the runner did not tear down.
  • Kubernetes job pods older than runner.workdir_cleanup_age, with their Secrets.

Set either option to 0 to turn cleanup off.

Post-task script (runner.post_task_script)

A host script that runs after each task's cleanup, for housekeeping like Docker pruning. The runner takes no new jobs until it exits or hits runner.post_task_script_timeout (default 5m). Its output goes to the runner log.

On Windows, use an .exe, .bat or .cmd file, PowerShell scripts are not supported. See docs/post-task-script.md.

Local job logs (log.job.dir)

Set log.job.dir to keep a copy of every task's log, masked as in Gitea, with the job's result on the last line. Copies are kept for log.job.retention (default 168h), so keep it above runner.timeout. Only the runner's user can read them.

OpenTelemetry (OTEL_*)

Set OTEL_EXPORTER_OTLP_ENDPOINT in the runner's environment to send job traces and runner metrics to an OpenTelemetry collector. See docs/telemetry.md.

Languages
Go 90.6%
JavaScript 7.8%
Shell 1.1%
Makefile 0.3%
PowerShell 0.1%