Configuration

rungar reads its configuration from /etc/rungar/config.yaml, or the file --config names, when it starts: a changed file is taken up by restarting it. Unknown keys are rejected, and a file that does not load keeps the daemon from starting.

A file says which version of the configuration it is written for, in version. A later Rungar reads it as that version meant, and warns of anything in it that is deprecated – in its log, and from rungar validate – which rungar config migrate rewrites; see Upgrading.

A provider’s own keys, and the keys of the runner blocks, are its type’s to read: see Providers.

General

The daemon’s own settings. The sections after them are GitHub, the providers, the scale sets, the metrics and the events.

version

integer

version is the version of the configuration the file is written for: 1. A later Rungar reads the file as that version meant, warning of anything deprecated in it, and rungar config migrate rewrites it for the version that Rungar writes. Unset is 1, with a warning.

installation

string

installation names this Rungar, and is put on every runner it creates, so that two installations sharing a fleet never adopt each other’s runners. Unset derives one from the GitHub URL, which is right unless two installations serve the same GitHub.

reconcile_interval

duration, such as 30s or 5m

reconcile_interval is how often each scale set is compared with the fleet. Unset is 30s; at least 5s.

socket

string

socket is the Unix socket the daemon serves the command line on, used by every command but rungar serve, rungar validate and rungar config. It is readable and writable by the daemon’s user and group alone, and whoever can use it can remove runners and disable providers. It is an absolute path of at most 103 characters. Unset is /run/rungar/rungar.sock.

log_level

string

log_level is debug, info, warn or error. Unset is info.

log_format

string

log_format is text, a line of key=value pairs a record, or json, a JSON object a line, for a log collector to parse. Unset is text.

github

mapping

github is where the scale sets live and how Rungar authenticates.

github.url

string

url is the enterprise, organisation or repository the scale sets belong to: “https://github.com/my-org", or a GitHub Enterprise Server URL. An enterprise needs a token: GitHub does not let an App manage an enterprise’s runners.

github.app_client_id

string

app_client_id is the App’s client ID, which looks like “Iv1.abc123”.

github.app_installation_id

integer

app_installation_id is the App’s installation on the organisation or repository.

github.app_private_key

string

app_private_key is the App’s private key in PEM, and app_private_key_path a file holding it. Give one or the other.

github.app_private_key_path

string

See app_private_key, above.

github.token

string

token is a personal access token, and token_path a file holding one. Give one or the other, and neither with an App.

github.token_path

string

See token, above.

providers[]

list of mappings

providers are what runners are placed on: each one backend that creates machines, configured as its type reads it. Providers sharing settings can share them with a YAML anchor:

providers:
  - &dicer
    name: compute1
    type: dicer
    address: 10.10.0.101:7443
    tls: {ca_file: /etc/rungar/ca.pem}
  - <<: *dicer
    name: compute2
    address: 10.10.0.102:7443

providers[].name

string

name is what scale sets, logs and metrics call the provider.

providers[].type

string

type is the kind of backend: dicer, proxmox, gcp or aws. The rest of the entry is the type’s; see its reference.

providers[].weight

number

weight scales how attractive the provider is to placement: spread counts one of weight 2 as having half the runners it has, and pack tries the highest weights first. Unset is 1.

providers[].max_runners

integer

max_runners is the most runners the provider may have, of every scale set placed on it: a ceiling of your own, such as a cloud’s cost, where the backend would take more. A provider at it is not tried. Unset leaves it to the backend, which refuses a runner once it is full. It may not be negative.

providers[].disabled

boolean

disabled takes the provider out of placement, leaving the runners on it to finish their jobs.

providers[].runner

mapping, read by the provider

runner is the runner block every scale set on the provider starts from. A scale set’s block for the provider is written over it: its keys replace the provider’s, mappings are merged key by key, and a key set to null is cleared. Its keys are the provider type’s.

scale_sets[]

list of mappings

scale_sets are the scale sets the daemon runs, each with its own labels, ceiling and runner. Scale sets sharing a provider compete only for its room. With none, the daemon only serves the command line: what removing the last scale set with rungar scale-sets rm takes.

scale_sets[].name

string

name is the scale set’s name on GitHub, and the label workflows target it by. A daemon starting looks it up by name and adopts the scale set GitHub already has.

scale_sets[].labels

list of strings

labels are further labels workflows may target it by, beside its name. They need a feature flag on GitHub Enterprise Server before 3.21. GitHub keeps the labels a scale set was created with, so changing them does nothing to one that exists: delete it on GitHub to have Rungar create it with these.

scale_sets[].runner_group

string

runner_group is the runner group the scale set belongs to, which decides which repositories may use it. Unset is GitHub’s “Default” group.

scale_sets[].min_runners

integer

min_runners are kept idle and ready with nothing queued, so that a job does not wait for a machine to boot. A schedule may set another number during its windows. Unset is 0; it may not be more than max_runners.

scale_sets[].max_runners

integer

max_runners is the most runners alive at once, across every provider. It is also the capacity reported to GitHub, which stops GitHub assigning more jobs than the scale set can run. It is required, and at least 1.

scale_sets[].priority

integer

priority decides who gets the providers when there is not room for everyone. Higher wins, and scale sets of the same priority take turns. A scale set that finds a provider full holds lower priorities back from it for a while, so that the next room freed there is its own, rather than filled by smaller runners. Nothing is reserved in advance, and a running runner is never taken away.

scale_sets[].placement

string: spread or pack

placement is the order the providers are tried in: spread tries first the one with the fewest of the scale set’s runners for its weight, which evens them out; pack tries the highest weight first, which fills them one after another. Ties go in the order written. A provider that is full refuses, and the next is tried. Unset is spread.

scale_sets[].start_timeout

duration, such as 30s or 5m

start_timeout is how long a runner has to connect to GitHub before it is replaced: a new runner from when it was created, an idle one from when it was first found disconnected. It does not bound a job. Unset is 5m; at least 30s.

scale_sets[].max_idle_age

duration, such as 30s or 5m

max_idle_age is how old a runner not running a job may get before it is replaced, one at a time. It keeps a reserve from running jobs on an image long out of date, as with a moving tag such as latest. Unset is never; at least start_timeout.

scale_sets[].max_age

duration, such as 30s or 5m

max_age is how old any runner may get before it is removed, even one running a job, which fails. It bounds a job that hangs. A provider that can, as gcp does, also has its backend delete the machine a little later, should Rungar not be running then. Unset is never; at least start_timeout.

scale_sets[].paused

boolean

paused keeps the scale set from taking jobs: GitHub is told it has no room, no runner is created, not even min_runners, its idle runners are removed and its busy ones are left to finish. Its jobs wait on GitHub, which cancels one left queued for a day. rungar scale-sets pause and rungar scale-sets resume change it until the daemon restarts.

scale_sets[].schedule

mapping

schedule sets min_runners by time of day: windows of the week, each with the min_runners in force during it, such as 4 on weekdays from 08:00 to 19:00 and the scale set’s own, 0, otherwise. A change takes effect within reconcile_interval.

scale_sets[].schedule.timezone

string, an IANA time zone such as Europe/Vilnius

timezone is the IANA time zone the windows are in, such as Europe/Vilnius; a window keeps to the wall clock there across daylight saving. Unset is UTC.

scale_sets[].schedule.windows[]

list of mappings

windows are the times min_runners differs from the scale set’s own. The first window, in the order written, that the time falls in is in force; outside every window, the scale set’s min_runners is.

scale_sets[].schedule.windows[].days

list of days, such as [mon-fri, sun]

days are the days the window opens on: mon, tue, wed, thu, fri, sat and sun, or ranges of them such as mon-fri. It is required.

scale_sets[].schedule.windows[].from

string, a time of day such as “08:00”

from is when the window opens, as HH:MM. It is required.

scale_sets[].schedule.windows[].to

string, a time of day such as “08:00”

to is when the window closes, as HH:MM, or 24:00 for the end of the day. One earlier than from closes the next day: a window from 22:00 to 06:00 on fri runs into Saturday morning. It is required.

scale_sets[].schedule.windows[].min_runners

integer

min_runners are kept idle and ready while the window is in force, in place of the scale set’s min_runners. Unset is 0; it may not be more than max_runners.

scale_sets[].providers[]

list of mappings

providers are what the scale set’s runners are placed on, in order of preference: a name, or a name and a runner block for that provider alone, written over the provider’s.

providers:
  - compute1
  - name: compute2
    runner: {vcpus: 8, memory: 16GiB}

scale_sets[].providers[].name

string

name is the provider’s name.

scale_sets[].providers[].runner

mapping, read by the provider

runner is what the scale set’s runners on this provider are made of, in the provider type’s terms: a size, say. It is written over the provider’s own runner block, so it need only say what differs.

metrics

mapping

metrics configures the Prometheus endpoint, which is off unless enabled.

metrics.enable

boolean

enable serves the metrics. The endpoint has no authentication.

metrics.listen

string

listen is the address the metrics are served on, as host:port. Widening it makes them readable by anyone who can reach it. Unset is 127.0.0.1:9102.

events

mapping

events configures the event log, which rungar events shows: runners created, adopted, removed and lost, and why, and what providers refused.

events.file

string

file is where the events are kept, one JSON object a line, so that they outlive the daemon. Its directory is made if it is not there. Unset is /var/log/rungar/events.jsonl.

events.max_count

integer

max_count is how many events are kept: the most recent. Unset is 10000.

events.max_age

duration, such as 30s or 5m

max_age is how long an event is kept. Unset keeps each until max_count newer ones push it out.