Provisions self-hosted runners as systemd services. One host can run runners for multiple projects (e.g. gatehouse-api + gatehouse-ui); each project gets its own runner name, install dir, label, repo URL, and registration token.

Layout

ansible.cfg                 inventory + ssh defaults
inventory.ini               stage / prod host groups (set ansible_host)
group_vars/all.yml          pinned runner version + sha256, paths, env_file
host_vars/<host>.yml        runner_env + per-project `runners` matrix
tasks/install_project.yml   reads token, expands count -> N instances
tasks/install_one_runner.yml  download/verify/extract/register/service one runner
install-runner.yml          the playbook

Runner naming

name: <host>-<project>-<env>-<N> e.g. stage01-gatehouse-api-stage-1
dir: /home/github-runner/actions-runner-<project>-<N>
label: project_spec.label (e.g. stage-secuird-runner, stage-gatehouse-ui)
service: actions.runner.<owner>-<repo>.<name>.service

Tokens

Registration tokens are per-repo and expire ~1h after minting. Set one key per project in the repo .env (control node), referenced by token_env in host_vars:

RUNNER_TOKEN_GATEHOUSE_API=AXXX...
RUNNER_TOKEN_GATEHOUSE_UI=AYYY...

Mint each from the repo's Settings > Actions > Runners > New self-hosted runner (the value after --token), then run the playbook within the hour.

Run

cd deploy/ansible

# 1. Edit inventory.ini (set ansible_host / ansible_user) and host_vars/*.yml.
# 2. Refresh RUNNER_TOKEN_* in ../../.env.

ansible-playbook --syntax-check install-runner.yml
ansible-playbook install-runner.yml --check --diff --limit stage   # dry run
ansible-playbook install-runner.yml --limit stage                  # apply

Verify

# on the host
systemctl list-units 'actions.runner.*'
ls /home/github-runner/                # actions-runner-gatehouse-api-1, -2, ...

Each repo's Settings > Actions > Runners should list the runners as Idle with the expected label. Idempotent: re-running skips already-configured runners (--replace re-registers safely; creates: guards downloads/extract/config).

Notes

Bump runner_version + runner_sha256 together in group_vars/all.yml (sha256 from the GitHub release page).
deploy/deploy.sh needs the runner user to have passwordless sudo for nginx reload — add that sudoers drop-in separately (not yet automated here).
gatehouse-ui repo URL + label in host_vars are placeholders — confirm before first run.