# 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.