Skip to content
Try Gitea Cloud ☁️ for 30 days → Accelerate your Development & Deploys!
Support

Configuration

The options on this page apply to both backends. The examples put them under runtime; with the Kubernetes backend, put them under kubernetesRuntime instead. Options of one backend only are described on its page: Docker-in-Docker and Kubernetes. Storage and caches are described in Storage and caching.

gitea:
instanceUrl: "https://gitea.example.com"

instanceUrl is the URL the controller and the runners use to reach Gitea. It can be an address inside the cluster, such as the Service of a Gitea installed in it, and includes the path if Gitea is served under one. Jobs check out code and upload artifacts at the URL Gitea is configured with (its ROOT_URL), so job containers must be able to reach that one too.

Keep the registration token in a Secret in the namespace of the Runner, and refer to it in registrationTokenSecretRef:

Terminal window
kubectl -n <namespace> create secret generic runner-registration-token \
--from-literal=token=<registration token>
gitea:
registrationTokenSecretRef:
name: runner-registration-token
key: token
  • Only the controller uses the token. Runner pods receive the credentials of their own runner, never the token.
  • The value must not have leading or trailing whitespace, which --from-file adds when the file ends with a newline. The controller refuses such a value and reports a RegistrationTokenUnavailable warning. In a YAML manifest, write the token on one line under stringData.
  • Writing the token into the Runner as plain text with gitea.registrationToken is not recommended, as anyone who can read the Runner can then read the token. Use registrationTokenSecretRef instead. Only one of the two can be set.

Rotating the token: when the value of the Secret changes, every runner registers again with the new token and its pod is rebuilt, see How configuration changes are applied. Cache volumes are kept. The previous registrations stay in Gitea as offline runners, which you can delete on the runner page of Gitea.

If Gitea uses a self-signed certificate or one of an internal CA, turn off certificate verification, or neither the controller nor the runners can connect:

gitea:
skipTlsVerify: true # false by default

The controller cannot be given a CA certificate yet, so skipTlsVerify: true is the only way for now. Providing a CA will be supported in a later version.

skipTlsVerify applies to the controller and to the runners, not to the jobs. Job containers verify certificates themselves, for example when actions/checkout clones the repository, so the job images must trust the certificate of Gitea, or jobs fail. To trust the CA instead of skipping verification for other services the runners use, such as an internal registry or action repository, see the example in Init containers.

scalability:
minSize: 1 # runner pods kept when no job is waiting, 0 by default
maxSize: 10 # 10 by default
cpuRequest: "2"
memoryRequest: 4Gi
# cpuLimit: "4" # no limit when unset
# memoryLimit: 8Gi
  • minSize is the lowest number of runner pods, busy or idle. With minSize: 0 all runner pods are removed when idle, and the next job waits for a full start: possibly a new node, the image pull and the registration, usually a few minutes. Keep at least one runner when that wait matters. While all runner pods run jobs, a new job still waits for a new runner pod.
  • The resources apply to each runner pod with the Docker-in-Docker backend, and to the job container of each job pod with the Kubernetes backend, see Concurrency and scaling.

How the number of runner pods follows the queue:

  • Scaling up: when jobs are waiting, the controller adds in one step the runner pods for the jobs that idle runners cannot take. For example, with 2 idle runners and 5 waiting jobs, it adds 3 runner pods. With the Kubernetes backend, see Concurrency and scaling.
  • Scaling down: when no job is waiting, it removes one runner pod at a time, starting with the highest number, once that runner has been idle for about 5 minutes. Going from full load back to minSize therefore takes some time. While the runner with the highest number is busy, no runner pod is removed, even if others are idle.
  • Lowering maxSize removes the runner pods above the new maximum at once, whether they run jobs or not: their jobs have the shutdownTimeout of the runner to finish. Their volumes and registrations are deleted immediately too, instead of being kept for storage.cacheTTL.
  • Changing minSize or maxSize takes effect immediately, and rebuilds no other runner pod.

The current target is in the status of the Runner, and every change of it is reported as a ScaleUp or ScaleDown event:

Terminal window
kubectl -n <namespace> get runner <name> -o jsonpath='{.status.targetSize}'
kubectl -n <namespace> describe runner <name>

The labels of a Runner are the names jobs select with runs-on, each mapped to the image the job runs in. They have no default: every Runner lists at least one.

runtime:
labels:
ubuntu-latest: docker://docker.gitea.com/runner-images:ubuntu-latest # Docker-in-Docker
kubernetesRuntime:
labels:
ubuntu-latest: docker.gitea.com/runner-images:ubuntu-latest # Kubernetes, no prefix

With the Docker-in-Docker backend, a label can also have the value host: its jobs then run on the host, that is directly in the runner container, instead of in a job container that the runner creates for them. A job for which the workflow sets a container still runs in a job container.

The controller counts a waiting job when any label of its runs-on is one of the labels of the Runner, even if the job also needs labels the Runner does not have and so cannot run it. Hence two Runner resources whose tokens cover the same repositories should not share a label: a waiting job would scale up both, although only one of them can run it.

The same applies to runners outside the controller, such as ones registered by hand: the controller does not count them as idle capacity, so it may add runner pods that end up unused, and jobs with that label may run in different environments.

envs sets environment variables of every job of the Runner:

runtime:
envs:
- name: NPM_CONFIG_REGISTRY
value: "https://npm.example.com/"

They are not set in the runner container. Variables that the runner and Docker need, such as a proxy, go in runnerEnv.

The controller writes them into the runner configuration, and the runner sets them in every job. The runner first replaces ${NAME} in their values with its own environment variable NAME when it starts, such as one set with runnerEnv, and does not start if it is not set. Write a literal ${NAME} as $${NAME}.

runnerEnv and runnerEnvFrom set environment variables of the runner container itself, written like the env and envFrom of a Kubernetes container. With the Docker-in-Docker backend the Docker daemon runs in the same container and receives them as well.

runtime:
runnerEnv:
- name: HTTPS_PROXY
value: "http://proxy.example.com:8080"
- name: NO_PROXY
value: "gitea.example.com,.svc.cluster.local"
- name: NPM_TOKEN
valueFrom:
secretKeyRef:
name: runner-secrets
key: npm-token
runnerEnvFrom:
- configMapRef:
name: runner-env
  • The Secrets and ConfigMaps must be in the namespace of the Runner. When one, or one of its keys, is missing and not marked optional: true, the controller creates no runner pod and reports a BuildRunnerWorkerFailed warning.
  • Any change of a referenced Secret or ConfigMap, even of its labels or annotations, rebuilds the runner pods, see How configuration changes are applied.
  • runnerEnv wins over runnerEnvFrom for the same name.
  • GITEA_INSTANCE_URL, CONFIG_FILE, RUNNER_STATE_FILE, GITEA_RUNNER_LABELS and GITEA_RUNNER_ONCE, and POD_IP with the Kubernetes backend, are reserved: the controller sets some of them itself, and the others would change how the runner registers or picks up jobs. A Runner that sets them in runnerEnv is rejected. When a source of runnerEnvFrom holds one of them, with its prefix, the controller creates no runner pod.
  • Jobs that run on the host see these variables. Jobs that run in a job container of their own do not, except the proxy variables, see below.

With HTTP_PROXY, HTTPS_PROXY and NO_PROXY on the runner container, these go through the proxy:

  • the runner’s connections to Gitea, to action repositories, and to the cache server or S3 bucket;
  • with the Docker-in-Docker backend, the image pulls of the Docker daemon, unless its daemon.json sets proxies;
  • jobs, services and image builds: the runner passes the variables on to them, and adds the cache server and services to their NO_PROXY. Proxy variables set in envs take precedence.

NO_PROXY must list the addresses inside the cluster and the network that the runner reaches directly, or those requests go to the proxy too:

Address Missing from NO_PROXY
Gitea The runner does not come online
The built-in cache server (.svc.cluster.local, or cacheServer.host), an external cache server or the S3 endpoint The workflow cache stops working, without failing the job
Internal registries Job images cannot be pulled
Kubernetes backend: the API server, the IP in KUBERNETES_SERVICE_HOST of the runner pod or its network Job pods cannot be created, and jobs fail

${NAME} in envs passes a variable of the runner container on to the jobs, so its value appears neither in the Runner nor in the generated configuration:

runtime:
runnerEnv:
- name: NPM_TOKEN
valueFrom:
secretKeyRef:
name: runner-secrets
key: npm-token
envs:
- name: NPM_TOKEN
value: "${NPM_TOKEN}"

Job logs do not mask values passed this way. For values that must be masked in logs, or that only some repositories may use, use Gitea Actions secrets.

runnerInitContainers adds init containers to the runner pods, which run in order before the runner starts, for example to prepare files for it. They pass files to the runner through an emptyDirMounts directory, which the runner container mounts at its mountPath and the init containers mount by its volumeName.

This example merges an internal CA certificate from a ConfigMap with the certificates of the image, for the runner to reach services with certificates of that CA, such as an internal action repository. The runner reads the bundle from SSL_CERT_FILE, and git, which it uses for some downloads, from GIT_SSL_CAINFO:

runtime:
configMapMounts:
- volumeName: company-ca
configMapName: company-ca # holds the certificates as *.crt
mountPath: /etc/company-ca
readOnly: true
emptyDirMounts:
- volumeName: ca-bundle
mountPath: /etc/ca-bundle
readOnly: true
runnerInitContainers:
- name: ca-bundle # no image: the runner image
command: ["sh", "-c", "cat /etc/ssl/certs/ca-certificates.crt /in/*.crt > /out/ca-certificates.crt"]
volumeMounts:
- name: company-ca
mountPath: /in
readOnly: true
- name: ca-bundle
mountPath: /out
runnerEnv:
- name: SSL_CERT_FILE
value: /etc/ca-bundle/ca-certificates.crt
- name: GIT_SSL_CAINFO
value: /etc/ca-bundle/ca-certificates.crt
  • An init container is written like a Kubernetes container, with these fields only: name, image, imagePullPolicy, command, args, workingDir, env, envFrom, resources, securityContext and volumeMounts. Sidecars (restartPolicy) and probes are not supported. The names install-registration, chown-cache and runner are taken by the controller.
  • They run after the init containers that the controller adds to each runner pod, such as install-registration. Without image they use the runner image and its imagePullPolicy, without resources those of the runner container. An image of their own is pulled with the imagePullSecrets of the Runner.
  • They can mount the volumes of configMapMounts, secretMounts and emptyDirMounts, and of pvcMounts with the Docker-in-Docker backend.
  • They do not mount a ServiceAccount token, so they cannot use the Kubernetes API.
  • With the Kubernetes backend they must meet the restricted Pod Security Standard: no root, no privileged mode, no privilege escalation, no capabilities beyond NET_BIND_SERVICE. Unset allowPrivilegeEscalation and capabilities.drop default to false and ["ALL"]. Otherwise the Runner is rejected, or the controller creates no runner pod and reports a BuildRunnerWorkerFailed warning. The Docker-in-Docker backend sets no such limit.
  • When one exits with an error or cannot start, for example because its image cannot be pulled, the runner does not start, the kubelet retries, and the controller reports a RunnerInitContainerFailed warning with the exit code and the end of the log.
  • They must finish within 15 minutes: a runner pod whose runner is not online in Gitea 15 minutes after the pod started, image pulls and init containers included, is deleted and created again, see Runner pods that do not come online. That also happens when an init container keeps failing.
  • Changing runnerInitContainers, or a Secret or ConfigMap their env or envFrom reads, rebuilds the runner pods. Changing the content of a mounted ConfigMap or Secret does not.

Besides pvcMounts of the Docker-in-Docker backend, three kinds of volumes can be mounted into the runner container:

runtime:
configMapMounts:
- volumeName: extra-config
configMapName: runner-extra-config
mountPath: /etc/runner-extra
readOnly: true
secretMounts:
- volumeName: extra-secret
secretName: runner-extra-secret
mountPath: /etc/runner-secret
readOnly: true
emptyDirMounts:
- volumeName: prepared
mountPath: /etc/prepared
medium: Memory # empty for the node's disk; Memory counts against the pod's memory
sizeLimit: 64Mi # the pod is evicted beyond it
  • configMapMounts and secretMounts also take items, defaultMode and optional, as the volumes of a pod do.

  • The volumeName of every mount must be unique, and must not be one of these names, which the controller reserves for its own volumes whether or not the Runner uses them:

    • runner-config
    • runner-data
    • runner-registration
    • runner-cache
    • runner-action-cache
    • cache-server-secret
    • cache-s3-credentials
    • runner-job-tmpfs
    • no-service-account-token

    Otherwise the controller creates no runner pod and reports a BuildRunnerWorkerFailed warning that names the volume, and the running runner pods are kept.

  • The volumes of configMapMounts, secretMounts and emptyDirMounts are mounted into the runner container, not into job containers.

A runner pod is rebuilt when its configuration changes: the image, labels, environment variables, init containers and the other options of the runner pod, a Secret or ConfigMap read by runnerEnv, runnerEnvFrom or an init container’s environment, a rotated registration token, cache server key or S3 key, and a cache volume that reached storage.cacheMaxAge. Rebuilding never interrupts a job:

  • A runner pod that runs no job is rebuilt immediately.
  • Docker-in-Docker backend: a runner pod that runs a job is rebuilt after the job, with RollDeferred events meanwhile.
  • Kubernetes backend: a runner pod that runs jobs is drained: it takes no new jobs, and is rebuilt once the jobs it has are done. One runner pod of a Runner is drained at a time, and the other runner pods take the waiting jobs, scaling up if needed. The events are RollDeferred while it waits and DrainWorker when draining starts.

The built-in cache server is rebuilt immediately when its configuration changes, see Built-in cache server.

nodeSelector:
node-pool: runners
tolerations:
- key: dedicated
operator: Equal
value: runner
effect: NoSchedule
affinity: {} # a standard Kubernetes affinity
imagePullSecrets:
- name: <registry credentials>

These fields sit at the top of spec, not under runtime. To dedicate nodes to the runners, taint them so that other pods are not scheduled on them, and tolerate the taint in tolerations:

  • tolerations also apply to the built-in cache server. It does not use nodeSelector or affinity, and runs on any node that can reach its volume.
  • DaemonSets on these nodes, especially the node plugin of the storage driver, must tolerate the taint too, or the volumes of the runner pods cannot be attached.
  • Runner pods and the built-in cache server carry the annotation karpenter.sh/do-not-disrupt: "true", so Karpenter does not remove their nodes to consolidate. Nodes of the runners kept by minSize therefore stay.
  • With the Kubernetes backend, these fields apply to the runner pods only. Job pods take theirs from the job pod template.
  • imagePullSecrets are the credentials for the runner image, which the runner pods and the built-in cache server run, and for the images of init containers. They are not used for job images: see Private job images of the Docker-in-Docker backend and Private job images of the Kubernetes backend.
  • Changing them rebuilds the runner pods as described in How configuration changes are applied, and the built-in cache server immediately.

The controller generates the configuration file of the runner (config.yaml) from the Runner. To write it yourself, put it in a ConfigMap in the namespace of the Runner, under the key config.yaml, and name it in runnerConfigMapName:

runtime:
runnerConfigMapName: my-runner-config

The controller then mounts it as it is, and:

  • writes none of the options it would otherwise put into the configuration: the images of labels, envs, jobTmpfs.tmpSize, the cache settings, and the container.valid_volumes of pvcMounts;

  • creates no built-in cache server, so configure the cache in the file;

  • still acts on some options itself, so keep the file in line with them:

    The controller uses To Keep in the file
    The names of labels Count the waiting jobs The same names in runner.labels, by which the runner picks up jobs
    shutdownTimeout Set terminationGracePeriodSeconds The same value in runner.shutdown_timeout
    gitea.skipTlsVerify Connect to Gitea The same value in runner.insecure
    One job per runner pod (Docker-in-Docker) Plan scaling runner.capacity: 1. For the Kubernetes backend, see there

When writing the file:

  • Set host.workdir_parent: /cache/act_workdir, as the generated configuration does, so that downloaded actions are kept on the action cache volume.
  • Leave runner.file unset: the controller provides the registration of the runner itself.

With the Kubernetes backend, see also Using your own runner configuration there. The keys of the configuration file are described in the runner’s config.example.yaml.