docs/runner-docs/configuration.md

sidebar_position

sidebar_position
3

Configuration

The runner works without a configuration file. Create one to change a default:

gitea-runner config init
gitea-runner config set runner.capacity 4
gitea-runner -c config.yaml daemon

config init writes a minimal config.yaml in the working directory. Pass the file with -c when running register, daemon or cache-server. These commands do not find configuration files automatically. The runner reads its configuration only at startup. Restart it after each change.

Editing

The config command edits the configuration file in place and preserves its comments:

gitea-runner config set runner.timeout 90m
gitea-runner config set runner.envs.MY_VAR value
gitea-runner config add container.valid_volumes '/data/**'
gitea-runner config remove container.valid_volumes '/data/**'
gitea-runner config get runner.capacity

A key is the path to a YAML value, with dots between levels. The command rejects unknown keys and values of the wrong type before changing the file. Without -c, these commands look for config.yaml or config.yml in the working directory, then in the directory containing the binary.

gitea-runner config generate prints every option with its default and a description. This matches the example configuration.

Use ${NAME} in a value to read an environment variable from the runner's environment. The configuration fails to load if NAME is unset. Use $${NAME} for a literal ${NAME}:

runner:
  capacity: ${RUNNER_CAPACITY}

Common options

Option	Default	Description
runner.capacity	1	Maximum number of jobs that can run at once.
runner.timeout	3h	Maximum job duration. Gitea's own job timeout may stop a job earlier.
runner.shutdown_timeout	0s	Time to let running jobs finish before canceling them during shutdown.
runner.envs		Environment variables for every job.
runner.env_file		File containing additional environment variables for every job.
runner.labels		See Labels.
runner.insecure	false	Skip verification of Gitea's TLS certificate.
runner.client_cert_file, runner.client_key_file		Client certificate and key for a Gitea instance that requires mutual TLS.
runner.extra_headers		HTTP headers for requests to Gitea, for example for a reverse proxy.
runner.github_mirror		URL to use instead of https://github.com when downloading actions from GitHub.
container.network		Docker network for job containers. If empty, the runner creates a network for each job.
container.options		Additional docker run options for every job container.
container.privileged	false	Run job containers in privileged mode. See Jobs.
container.valid_volumes		Volumes and host paths that workflows may mount.
container.force_pull	false	Pull job images even when they are already present.
log.level	info	Verbosity of the runner's log.

See Caching, hooks and monitoring for their configuration options.