configuration.md

Configuration reference

github-runner uses a TOML configuration file. The default path is /etc/github-runner/config.toml, overridden with --config.

Environment variable interpolation

String values support ${VAR_NAME} syntax. The variable is replaced with its environment value at load time. Missing variables resolve to an empty string with a warning logged.

token = "${RUNNER_TOKEN}"

Hot reload

The runner watches the config file for changes and reloads on modification. Send SIGHUP to trigger a reload manually. Invalid configs are rejected with a log warning; the previous config remains active.

---

[global]

Application-wide settings.

Field	Type	Default	Description
log_level	string	"info"	Log level: debug, info, warn, error
log_format	string	"json"	Log format: json, text
metrics_listen	string	"127.0.0.1:9252"	Address for the Prometheus metrics endpoint
health_listen	string	"127.0.0.1:8484"	Address for the health check endpoints
shutdown_timeout	duration	"30s"	Max wait time for in-flight jobs during shutdown
check_interval	duration	"3s"	Interval between job polling requests

[global.api]

GitHub API client settings.

Field	Type	Default	Description
base_url	string	"https://api.github.com"	API base URL (change for GitHub Enterprise)
timeout	duration	"30s"	HTTP request timeout
max_retries	int	3	Max retry attempts for transient failures
retry_backoff	duration	"1s"	Base duration for exponential backoff

---

[[runners]]

Each [[runners]] block defines an independent runner pool. Multiple pools can be configured with different executors and concurrency.

Field	Type	Default	Description
name	string	required	Unique name for this runner pool
url	string	required	GitHub repository, org, or enterprise URL
token	string	required	Registration token (supports ${VAR})
executor	string	required	Executor type: shell, docker, kubernetes, firecracker
concurrency	int	1	Number of parallel jobs this pool handles
labels	string[]	[]	Labels for job routing
work_dir	string	""	Working directory for job workspaces (must be absolute)
shell	string	"bash"	Default shell for run: steps
ephemeral	bool	false	De-register after one job

---

[runners.docker]

Docker executor settings. Required when executor = "docker".

Field	Type	Default	Description
image	string	"ubuntu:22.04"	Default container image
privileged	bool	false	Run containers in privileged mode
pull_policy	string	"if-not-present"	Image pull policy: always, if-not-present, never
memory	string	""	Memory limit (e.g., "2g", "512m")
cpus	float	0	CPU limit (fractional cores, e.g., 2.0)
network_mode	string	"bridge"	Docker network mode: bridge, host, none
volumes	string[]	[]	Volume mounts in host:container:mode format
allowed_images	string[]	[]	Glob patterns for allowed images
dns	string[]	[]	DNS servers for containers
cap_drop	string[]	["ALL"]	Linux capabilities to drop
cap_add	string[]	[]	Linux capabilities to add
runtime	string	""	OCI runtime (e.g., "sysbox-runc")
tmpfs	map	{}	tmpfs mounts: { "/tmp" = "rw,noexec,size=512m" }

---

[runners.kubernetes]

Kubernetes executor settings. Required when executor = "kubernetes".

Field	Type	Default	Description
namespace	string	"github-runner"	Target namespace
image	string	"ubuntu:22.04"	Default container image
service_account	string	""	Kubernetes service account
cpu_request	string	"500m"	CPU resource request
cpu_limit	string	"2000m"	CPU resource limit
memory_request	string	"512Mi"	Memory resource request
memory_limit	string	"4Gi"	Memory resource limit
node_selector	map	{}	Node selector key-value pairs
pull_policy	string	"IfNotPresent"	Image pull policy

---

[runners.cache]

Cache settings for the runner pool.

Field	Type	Default	Description
type	string	"local"	Backend: local, s3, gcs
path	string	""	Directory for local cache
max_size	size	"0"	Max cache size (e.g., "10g")

[runners.cache.s3]

S3-compatible cache backend settings.

Field	Type	Default	Description
bucket	string	""	S3 bucket name
region	string	""	AWS region
endpoint	string	""	Custom endpoint for S3-compatible services
prefix	string	""	Key prefix within the bucket

[runners.cache.gcs]

Google Cloud Storage cache backend settings (scaffold).

Field	Type	Default	Description
bucket	string	""	GCS bucket name
prefix	string	""	Object prefix within the bucket

---

[runners.environment]

Key-value pairs injected as environment variables into every job.

[runners.environment]
CI = "true"
RUNNER_POOL = "docker-fast"

---

Type reference

Duration

Standard Go duration strings: "30s", "5m", "1h", "100ms".

Size

Human-readable byte sizes (case-insensitive):

Suffix	Unit
b or none	bytes
k, kb	kilobytes (1024)
m, mb	megabytes (1024^2)
g, gb	gigabytes (1024^3)
t, tb	terabytes (1024^4)

Fractional values are supported: "1.5g".

---

Validation rules

The config is validated at load time. All errors are collected and reported together. The following rules are enforced:

• At least one [[runners]] block must be defined
• Each runner must have name, url, token, and executor
• No duplicate runner names
• executor must be one of: shell, docker, kubernetes, firecracker
• concurrency must be > 0
• work_dir must be an absolute path (if set)
• url must be a valid HTTP/HTTPS URL
• Docker config must have a non-empty image and valid pull_policy when executor is docker
• Kubernetes config must have a non-empty namespace and image when executor is kubernetes
• log_level must be one of: debug, info, warn, error
• log_format must be one of: json, text

Example

See configs/config.example.toml for a fully annotated example with all available options.