CI and builds

Gitea Actions Runners

1.Gitea Actions in brief

  • Built into Gitea, with GitHub Actions workflow syntax. Files live in .gitea/workflows (else .github/workflows). On since Gitea 1.21. These notes use Gitea 28.1.0 and Gitea Runner 5.0.0.
  • The server queues jobs, runners execute them. No CRDs or controller (contrast ARC).
  • act_runner became Gitea Runner at v1.0.0 (2026-05-05) : image gitea/runner (the old one stopped at 0.6.1).

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 unless DEFAULT_ACTIONS_URL = self). See NetworkPolicy.
Gitea 28 : run queue job: runs-on ubuntu-latest 1. FetchTask poll 2 to 5s 2. task: steps, secrets, job token 4. logs, step state gitea-runner daemon .runner identity, labels, capacity 3. by label schema docker:// job container, per-job network kubernetes:// one Pod per job host runner's own machine 5 5 : every backend fetches checkout, artifacts (job token)

3.Registering a runner

LevelTakes jobs fromToken in the UI
Instanceevery repository/-/admin/actions/runners
Organizationthat org's repositories/org/<org>/settings/actions/runners
Userthat user's repositories/user/settings/actions/runners
Repositorythat repository/<owner>/<repo>/settings/actions/runners
  • The docs print the org path without /org/ : a 404. A token is reusable until reset.
  • register trades 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

LabelJob runsNeeds
ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latestin a container from that imagea Docker daemon
ubuntu-latest:kubernetes://...as its own Pod (v4.1.0+)Kubernetes 1.30+, a Role, an image with sh, tar, tail, env
linux-amd64:hoston the runner's machine, no isolationtools installed there; no service containers unless the job sets container:
  • Grammar <name>[:<schema>[:<args>]]. A runner gets a job only if it has every runs-on label. Since 5.0.0 a job without runs-on fails. No match : it waits, then is cancelled after 24h.
  • Labels come only from the runner (config, GITEA_RUNNER_LABELS or --labels), re-declared on every start. Gitea cannot edit them. Never call a host label ubuntu-latest.

5.Commands

CommandDoes
gitea --config /etc/gitea/app.ini actions generate-runner-token --scope myorgPrint 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://IMAGERegister. --token-file keeps the token out of ps
kubectl -n ci logs runner-0 -c runner | grep -i declareConfirm 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 StatefulSetRootless dindkubernetes:// job Pods
Privileged containeryes, dockerdyes, still privilegedno
Docker actionsyesyesno, the job fails
Servicescontainers on the job networksameextra containers, on localhost
Job limitsthe runner Pod's, sharedsameeach job Pod's own, from pod_template
Extra RBACnonenoneRole : pods, pods/exec, pods/log, secrets

2.The DinD StatefulSet

runner Pod (ordinal 0) init: docker docker:dind, privileged restartPolicy: Always container: runner gitea/runner docker.sock (emptyDir) starts job containers per-job network PVC /var/lib/docker (image cache) PVC /data (.runner) outbound HTTPS only Gitea StatefulSet : concurrency = replicas x runner.capacity
  • A StatefulSet : each Pod keeps its own .runner via volumeClaimTemplates.
  • dind is a native sidecar : up before the runner, down after it (1.29+, GA 1.33, Pods). require_docker: true makes the runner wait.
  • Give dind's data root a volume, or every new Pod re-pulls all job images.
  • terminationGracePeriodSeconds above shutdown_timeout (upstream : 3h). Pin the tags in upstream's statefulset-dind.yaml.

3.kubernetes:// job Pods

  • ShapeNew in v4.1.0. One bare Pod per job, not a Job : a job container plus one per service.
  • NeedsKubernetes 1.30+, a namespaced Role (RBAC). Job Pods get no SA token by default.
  • Templatepod_template merges into every job Pod (name: job, $services). Set resources there. pod_templates.<label> add per-label overrides, such as a nodeSelector.
  • FailsDocker actions, docker:// steps, options, volumes, credentials. Pull secrets go in the template.

4.config.yaml keys that bite

KeyDefaultWhy it matters
runner.capacity1jobs at once per process; each concurrent docker job takes a subnet from the daemon's pool
runner.shutdown_timeout0srunning jobs are cancelled at once on SIGTERM, and Gitea does not re-queue them
container.privilegedfalsetrue makes every job container privileged and turns off option stripping
container.docker_host""jobs get the daemon's socket; "-" keeps it out
metrics.enabledfalse/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 with capacity: 1 over one big one.
  • No upstream controller, CRD or scaler, and no KEDA scaler (contrast ARC). The chart gitea/helm-actions v0.1.2 defaults to runner 2.0.1 : pin your own tag.
  • 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 privileged level.
  • 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

workflow container.options runner strips --pid, --cap-add, --security-opt, --device ... unless container.privileged: true job container docker.sock (per-job proxy) dind daemon privileged the node docker_host: "-" cuts the socket edge above
  • Since 3.0.0 workflow container.options lose host-escape flags and --privileged is ignored (more in 5.0.0). container.privileged: true turns that off.
  • The runner's own options are trusted (unfiltered since 3.3.1). A workflow's --env-file and --label-file always 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, alias GITHUB_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). No id-token exists, so no keyless signing from jobs (Image Signing).

4.Differences from GitHub Actions

AreaGitea 28.1, runner 5.0
Contextsgitea.*, with github.* as an alias. No GraphQL.
Actions without a hostcloned from github.com unless DEFAULT_ACTIONS_URL = self
Token scopesno statuses, checks, deployments, id-token; adds code, releases, wiki, projects
runs-onlabels only, no runner groups; required since runner 5.0.0

5.Upgrading across majors

ToCheck
1.0renamed; since 1.0.5 env overrides like GITEA_RUNNER_CAPACITY are ignored : use config.yaml
2.0DOCKER_USERNAME and DOCKER_PASSWORD no longer give pull credentials
3.0one process per .runner, option stripping, cache v2 on
4.0with cache.external_server jobs reach the cache through their runner; valid_volumes globs
5.0git 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_RETENTION_DAYS) : set 0 first 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.