ci: add gitea + runner

deploy/ansible/README.md

@@ -1,35 +1,41 @@
-# GitHub Actions self-hosted runners — Ansible
+# Gitea Actions self-hosted runners — Ansible
 
-Provisions self-hosted runners as **systemd services**. One host can run runners for
+Provisions `act_runner` instances 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.
+runner name, install dir, label set, 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
+group_vars/all.yml          pinned act_runner version + sha256, gitea_instance URL
 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
+tasks/install_one_runner.yml  download/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`
+- name:    `<host>-<project>-<env>-<N>`  e.g. `stage01-gatehouse-api-stage-1`
+- dir:     `/home/gitea-runner/act-runner-<project>-<N>`
+- labels:  `project_spec.labels` (comma-separated, e.g. `self-hosted,linux,stage`)
+- service: `gitea-runner-<project>-<N>.service`
+
+## Before first run — pin act_runner version
+
+1. Check [act_runner releases](https://gitea.com/gitea/act_runner/releases) for the latest stable version.
+2. Download `act_runner-<version>-linux-amd64.sha256` from the release page.
+3. Update `act_runner_version` and `act_runner_sha256` in `group_vars/all.yml`.
 
 ## Tokens
 
 Registration tokens are **per-repo and expire ~1h after minting**. Exported as env
 vars on the control node, named by each project's `token_env` in `host_vars`.
 
-Mint each from the repo's **Settings > Actions > Runners > New self-hosted runner**
-(the value after `--token`), then run the playbook within the hour.
+Mint each from the repo's **Settings → Actions → Runners → Create new runner token**,
+then run the playbook within the hour.
 
 ## Run
 
@@ -37,7 +43,8 @@ Mint each from the repo's **Settings > Actions > Runners > New self-hosted runne
 cd deploy/ansible
 
 # 1. Edit inventory.ini (set ansible_host / ansible_user) and host_vars/*.yml.
-# 2. Export fresh tokens (leading space keeps them out of shell history):
+# 2. Fill in act_runner_version + act_runner_sha256 in group_vars/all.yml.
+# 3. Export fresh tokens (leading space keeps them out of shell history):
  export RUNNER_TOKEN_GATEHOUSE_API=xxx
  export RUNNER_TOKEN_GATEHOUSE_UI=yyy
 
@@ -50,18 +57,28 @@ ansible-playbook install-runner.yml --limit stage                  # apply
 
 ```bash
 # on the host
-systemctl list-units 'actions.runner.*'
-ls /home/github-runner/                # actions-runner-gatehouse-api-1, -2, ...
+systemctl list-units 'gitea-runner-*'
+ls /home/gitea-runner/                # act-runner-gatehouse-api-1, ...
 ```
 
-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).
+Each repo's **Settings → Actions → Runners** should list the runners as **Idle** with
+the expected labels. Idempotent: re-running skips already-registered runners
+(`creates: .runner` guards re-registration; binary download is checksum-gated).
+
+## Migrating from GitHub Actions runners
+
+Stop and remove the old runners on any existing host before re-running:
+
+```bash
+sudo su - github-runner -c "cd ~/actions-runner-*/; ./svc.sh stop && ./svc.sh uninstall"
+sudo userdel -r github-runner   # optional — removes home dir too
+```
 
 ## Notes
 
-- Bump `runner_version` + `runner_sha256` together in `group_vars/all.yml`
-  (sha256 from the GitHub release page).
+- Bump `act_runner_version` + `act_runner_sha256` together in `group_vars/all.yml`.
+- Labels in `host_vars/<host>.yml` must match the `runs-on:` values in workflow files.
 - `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.
+  add that sudoers drop-in separately (not yet automated here). Update the username from
+  `github-runner` to `gitea-runner` in that drop-in.
+- `prod01.ansible_host` in `inventory.ini` is still `CHANGE_ME` — fill in before running prod.