CI and builds
Gitea Actions Runners
1.Gitea Actions in brief
- Built into Gitea, with GitHub Actions workflow syntax. Files live in
.gitea/(elseworkflows .github/). On since Gitea 1.21. These notes use Gitea 28.1.0 and Gitea Runner 5.0.0.workflows - The server queues jobs, runners execute them. No CRDs or controller (contrast ARC).
act_runnerbecame Gitea Runner at v1.0.0 (2026-05-05) : imagegitea/(the old one stopped at 0.6.1).runner
2.The pull model
- The runner connects out to Gitea and polls every 2s, backing off to 5s when idle. Gitea never dials it : no Service, no inbound port. Offline after a minute.
- Plan four connections : runner and job containers to Gitea (never register with
localhost), runner and job containers to the internet (actions come from github.com unlessDEFAULT_). See NetworkPolicy.ACTIONS_ URL = self
3.Registering a runner
| Level | Takes jobs from | Token in the UI |
|---|---|---|
| Instance | every repository | /-/ |
| Organization | that org's repositories | /org/ |
| User | that user's repositories | /user/ |
| Repository | that repository | /<owner>/ |
- The docs print the org path without
/org/: a 404. A token is reusable until reset. registertrades it for the runner's own credential, written to .runner. Persist it, never copy it : lose it and the runner registers anew, leaving a stale offline entry.- Ephemeral runners (Gitea 1.24+) take one job, credentials revoked on assignment. You start them.
4.Labels pick where a job runs
| Label | Job runs | Needs |
|---|---|---|
ubuntu-latest: | in a container from that image | a Docker daemon |
ubuntu-latest: | as its own Pod (v4.1.0+) | Kubernetes 1.30+, a Role, an image with sh, tar, tail, env |
linux-amd64: | on the runner's machine, no isolation | tools installed there; no service containers unless the job sets container: |
- Grammar
<name>[:<schema>[:<args>]]. A runner gets a job only if it has everyruns-onlabel. Since 5.0.0 a job withoutruns-onfails. No match : it waits, then is cancelled after 24h. - Labels come only from the runner (config,
GITEA_orRUNNER_ LABELS --labels), re-declared on every start. Gitea cannot edit them. Never call a host labelubuntu-latest.
5.Commands
| Command | Does |
|---|---|
gitea --config /etc/gitea/app.ini actions generate-runner-token --scope myorg | Print a token on the Gitea host (no scope = instance) |
kubectl -n ci create secret generic runner-secret --from-literal=token="$TOKEN" | Store it with no trailing newline, unlike echo | base64 |
gitea-runner register --no-interactive --instance URL --token-file /run/token --labels ubuntu-latest:docker://IMAGE | Register. --token-file keeps the token out of ps |
kubectl -n ci logs runner-0 -c runner | grep -i declare | Confirm it registered and declared its labels |
In short : A Gitea runner polls Gitea for jobs, matches them by every
runs-on label, and runs each one in a container, a Pod or on the host. Register it once and keep its .runner file.1.Three shapes
The trade : full features and privileged, or unprivileged and fewer features. Upstream recommends the dind image for container jobs : jobs never get the host's socket. Privileged dind is node root (Image Builds, Pod Security).
| DinD StatefulSet | Rootless dind | kubernetes:// job Pods | |
|---|---|---|---|
| Privileged container | yes, dockerd | yes, still privileged | no |
| Docker actions | yes | yes | no, the job fails |
| Services | containers on the job network | same | extra containers, on localhost |
| Job limits | the runner Pod's, shared | same | each job Pod's own, from pod_ |
| Extra RBAC | none | none | Role : pods, pods/, pods/, secrets |
2.The DinD StatefulSet
- A StatefulSet : each Pod keeps its own
.runnerviavolume.Claim Templates - dind is a native sidecar : up before the runner, down after it (1.29+, GA 1.33, Pods).
require_makes the runner wait.docker: true - Give dind's data root a volume, or every new Pod re-pulls all job images.
terminationaboveGrace PeriodSeconds shutdown_(upstream : 3h). Pin the tags in upstream'stimeout statefulset-.dind.yaml
3.kubernetes:// job Pods
- ShapeNew in v4.1.0. One bare Pod per job, not a Job : a
jobcontainer plus one per service. - NeedsKubernetes 1.30+, a namespaced Role (RBAC). Job Pods get no SA token by default.
- Template
pod_merges into every job Pod (template name: job,$services). Set resources there.pod_add per-label overrides, such as atemplates.<label> nodeSelector. - FailsDocker actions,
docker://steps,options,volumes,credentials. Pull secrets go in the template.
4.config.yaml keys that bite
| Key | Default | Why it matters |
|---|---|---|
runner. | 1 | jobs at once per process; each concurrent docker job takes a subnet from the daemon's pool |
runner. | 0s | running jobs are cancelled at once on SIGTERM, and Gitea does not re-queue them |
container. | false | true makes every job container privileged and turns off option stripping |
container. | "" | jobs get the daemon's socket; "-" keeps it out |
metrics. | false | /metrics, /healthz, /readyz on 127.0.0.1:9101, no auth (Prometheus) |
config init writes the file, config set edits a key. config generate is a commented reference, not a file to copy.
5.Sizing, and no autoscaler
- Concurrency = replicas x
runner.capacity. Maintainers advise more runners withcapacity: 1over one big one. - No upstream controller, CRD or scaler, and no KEDA scaler (contrast ARC). The chart
gitea/v0.1.2 defaults to runner 2.0.1 : pin your own tag.helm- actions - Job containers on Docker's 1500 MTU hang on big transfers over a smaller pod network : lower dockerd's
--mtu(job networks inherit it since 5.0.0).
Seen in practicePitfall : renaming a runner StatefulSet to tidy its name. Its selector and
volumeClaimTemplates are immutable, so the new one starts on fresh volumes, every Pod registers anew and the old entries stay offline. Do better : pick a neutral name up front. If you must rename, delete the stale runners.In short : Run Gitea runners as a StatefulSet so each Pod keeps its registration, and size the pool yourself. Privileged dind runs every workflow;
kubernetes:// Pods trade features for no privileges.1.Trust model
- Privileged dind is node root for every workflow author, and rootless dind is still privileged (Image Builds). Pod Security Baseline rejects it, a native sidecar included : the runner namespace needs the
privilegedlevel. - Mitigate with a tainted node pool (scheduling), trusted repositories, egress limits, or
kubernetes://Pods. - An instance runner takes every repository's jobs : with stranger PRs, use repository or organization runners.
2.What the runner strips
- Since 3.0.0 workflow
container.optionslose host-escape flags and--privilegedis ignored (more in 5.0.0).container.privileged: trueturns that off. - The runner's own options are trusted (unfiltered since 3.3.1). A workflow's
--env-fileand--label-filealways fail.
Not a sandboxOn dind every job container gets the daemon's socket (a per-job proxy since 3.4.0) and can start privileged containers. No Docker needed ?
container.docker_host: "-".Seen in practicePitfall : setting
container.privileged: true so one repository's daemonless builds work (Buildah needs user namespaces the default seccomp profile blocks). Every job container on that runner turns privileged. Do better : run a separate privileged pool with its own label, since the runner's container.options reach every job on it too.3.Fork PRs, secrets and the job token
- Gitea decrypts owner and repo secrets and sends them to the runner inside the task. Fork pull requests, except
pull_request_target, get only the job token (GITEA_TOKEN, aliasGITHUB_TOKEN), clamped read-only. - Several approval-gate bypasses for fork PR runs were fixed in 2026, some only in 28.0 : keep Gitea current.
- The job token cannot publish packages : use a token with
write:package(Image Builds). Noid-tokenexists, so no keyless signing from jobs (Image Signing).
4.Differences from GitHub Actions
| Area | Gitea 28.1, runner 5.0 |
|---|---|
| Contexts | gitea.*, with github.* as an alias. No GraphQL. |
| Actions without a host | cloned from github.com unless DEFAULT_ |
| Token scopes | no statuses, checks, deployments, id-token; adds code, releases, wiki, projects |
runs-on | labels only, no runner groups; required since runner 5.0.0 |
5.Upgrading across majors
| To | Check |
|---|---|
| 1.0 | renamed; since 1.0.5 env overrides like GITEA_ are ignored : use config.yaml |
| 2.0 | DOCKER_ and DOCKER_ no longer give pull credentials |
| 3.0 | one process per .runner, option stripping, cache v2 on |
| 4.0 | with cache. jobs reach the cache through their runner; valid_ globs |
| 5.0 | git 2.34.1+ on the runner, ${NAME} expands in config, runs-on required |
- An upgrade is an image swap : check the env and config schema at the target tag. Registrations carry over.
- Gitea 28 deletes completed runs after 400 days (
RUN_) : setRETENTION_ DAYS 0first to keep history.
In short : Treat a privileged runner as root on its node : scope it, patch Gitea, and keep strangers' fork PRs away from it. Upgrades are an image swap, but read the breaking notes for each major.