Docs: record Gitea Actions runner operations

docs/gitea-actions-runner.md

@@ -0,0 +1,73 @@
+# Gitea Actions Runner
+
+Republic OS CI runs on the shared Hostinger production host through an
+organization-scoped Gitea Actions runner. The runner is platform
+infrastructure, not an application endpoint: it publishes no ports and does not
+participate in Traefik routing.
+
+## Current deployment
+
+- Gitea organization: `Influence-Tools`
+- Runner name: `hostinger-influence-tools-01`
+- Runner image: `gitea/act_runner:latest`
+- Workflow label: `ubuntu-latest`
+- Job image: `catthehacker/ubuntu:act-latest`
+- Persistent volume: `gitea-actions-runner-data`
+- Restart policy: `unless-stopped`
+- Runner limit: 0.75 CPU and 768 MiB memory
+- Job concurrency: one
+- Public ports: none
+
+The runner mounts `/var/run/docker.sock` so it can create a disposable job
+container for each workflow. Treat control of the runner container and its
+registration state as privileged host access.
+
+## Registration
+
+Create an organization-scoped registration token in Gitea under
+`Influence-Tools -> Settings -> Actions -> Runners`. Pass it to the runner as
+`GITEA_RUNNER_REGISTRATION_TOKEN` at initial registration only. Never commit the
+token, paste it into logs, or store it in this repository.
+
+The remaining non-secret settings are:
+
+```text
+GITEA_INSTANCE_URL=https://git.influence.tools
+GITEA_RUNNER_NAME=hostinger-influence-tools-01
+GITEA_RUNNER_LABELS=ubuntu-latest:docker://catthehacker/ubuntu:act-latest
+```
+
+Persist `/data` in the `gitea-actions-runner-data` volume and mount the Docker
+socket at `/var/run/docker.sock`. Attach the runner to the isolated Gitea Docker
+network. Do not publish a host port or attach it to the public proxy.
+
+## Verification
+
+```bash
+docker ps --filter name=gitea-actions-runner
+docker logs --tail 100 gitea-actions-runner
+docker inspect gitea-actions-runner \
+  --format 'restart={{.HostConfig.RestartPolicy.Name}} ports={{json .HostConfig.PortBindings}}'
+```
+
+In Gitea, confirm the runner is online and carries `ubuntu-latest`. A successful
+Republic OS run must complete checkout, `make build`, the clean-diff check, and
+`make validate`. Temporary containers named `GITEA-ACTIONS-TASK-*` should be
+removed after their jobs finish.
+
+## Backup and recovery
+
+Include the `gitea-actions-runner-data` volume in the Hostinger platform backup
+inventory. If registration state is lost, remove the stale runner entry in
+Gitea and register a replacement with a newly generated token. Registration
+tokens and runner credentials are secrets and must not be stored in Git.
+
+The runner is not required for application availability. If it misbehaves,
+stop it; Gitea will queue workflows until an eligible runner returns.
+
+## Removal
+
+Stop and remove the runner container, then remove its entry from the
+organization's Actions runner settings. Delete the persistent volume only after
+confirming no rollback or forensic need remains. Removing the runner does not
+affect Gitea repositories or deployed applications.