ci + ansible

2026-06-20 11:06:27 +07:00
parent a6d74d9316
commit 966578ed58
15 changed files with 637 additions and 30 deletions
@@ -0,0 +1,70 @@
+# GitHub Actions self-hosted runners — Ansible
+
+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
+
+```bash
+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
+
+```bash
+# 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.