diff --git a/docs/gitea-actions-runner.md b/docs/gitea-actions-runner.md new file mode 100644 index 0000000000..b6d67b75e7 --- /dev/null +++ b/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.