runpool.pools.example

# runpool pools: copy to ~/.config/runpool/pools
#
# What this machine is meant to have. `runpool apply` reconciles the machine to
# it; `runpool apply --dry-run` prints what would change and touches nothing.
#
# Every example below is commented out, so this file as shipped declares no
# pools and `runpool apply` on it does nothing. Uncomment and edit. An empty
# file is valid and means "I am not describing this machine here".
#
# This is the file to copy when a second machine should have the same pools.
# It holds no credentials and nothing machine-specific, so it is safe to keep
# in a dotfiles repository alongside anything else you carry between machines.
#
# Another path can be used instead, either for one run or for good:
#
#   runpool apply --file ./pools            one run, this file
#   RUNPOOL_POOLS_FILE=... runpool apply    one run, from the environment
#   RUNPOOL_POOLS_FILE in the config file   every run on this machine
#
# One pool per line, written exactly as its `register` arguments minus the word
# `register`:
#
#   <name>  --org ORG | --repo OWNER/REPO
#           [--count N]              runners in the pool; default 2
#           [--watch OWNER/REPO,...] org pools only, see below
#           [--labels LABEL,...]     extra runner labels, see below
#           [--allow-public]         repo pools only, and only consulted when
#                                    the pool is created
#
# Blank lines are ignored. A '#' comments out the line it is on and nothing
# else. A trailing '\' continues onto the next line, which is what keeps a long
# --watch list readable, and the line it continues onto has to say something,
# so a half-uncommented example is an error naming both lines rather than a
# pool quietly missing half of itself.
#
# Reconciliation goes one way. A pool here and not on the machine is created; a
# count or watch list that differs is changed; a pool on the machine and not
# here is reported and LEFT ALONE. Deleting a pool deregisters its runners with
# GitHub, so that stays an explicit `runpool remove <pool>`.
#
# Changing a pool's scope or target is reported as a conflict rather than
# applied, because the runners are registered against the old one. Remove the
# pool and apply again.

# --labels adds to what every runner in the pool carries already: self-hosted,
# the machine's OS and architecture, and the pool's own name. It cannot replace
# them, because GitHub assigns the first three whatever it is told, and the
# pool name is the routing contract. Naming one of them here is an error rather
# than a no-op.
#
# A label is letters, digits, dot, underscore and hyphen. That is narrower than
# GitHub allows, and deliberately: this file is word-split, and the value is
# written into a config file that every command SOURCES, so a space, a quote or
# a '$' would be a broken pool or worse. 'xcode-16.2' works; 'xcode 16' cannot.
#
# Applying a label change is the heaviest thing in this file. Labels live on
# GitHub's registration, so `apply` stands the pool down and re-registers every
# runner. Absent --labels means no extra labels, so a pool whose config was
# edited by hand to add one needs it declared here, or the next apply takes it
# away and whatever routed to it queues for ever.

# ---------------------------------------------------------------------------
# An organisation pool. Every repository in the org can use these runners.
# ---------------------------------------------------------------------------
# --watch names the repositories to poll for queued work while the pool is
# down. GitHub reports queued runs per repository and not per organisation, so
# without it an org pool never wakes on its own and every job waits for someone
# to run `runpool up`. Only repositories you actually point at the pool belong
# here: each one costs an API call per tick while the pool is down.
#
# A repo pool needs no --watch. It polls its own target, and giving it one is
# refused rather than ignored.

# acme  --org acme-inc --count 4 --watch acme-inc/api, acme-inc/web \
#       --labels xcode

# Long lists are easier to read split across lines. Uncomment every line of it
# or none of them:
#
#   acme  --org acme-inc --count 4 \
#         --watch acme-inc/api, acme-inc/web \
#         --watch acme-inc/infra

# ---------------------------------------------------------------------------
# A personal repository. GitHub has no user-account scope, so a repo outside an
# organisation needs its own pool and cannot borrow the one above.
# ---------------------------------------------------------------------------

# side  --repo me/side-project --count 1

# ---------------------------------------------------------------------------
# A second machine
# ---------------------------------------------------------------------------
# Copy this file across, drop the pools that machine should not have, and run
# `runpool apply --dry-run` before `runpool apply`. Pool names are per machine,
# so two machines may use the same names against the same org; the runners
# register under distinct names because those carry the hostname.