ouranos/docs/gitea_runner.md

Gitea Act Runner

Overview

Gitea Actions is Gitea's built-in CI/CD system, compatible with GitHub Actions workflows. The Act Runner is the agent that executes these workflows. It picks up jobs from a Gitea instance, spins up Docker containers for each workflow step, runs the commands, and reports results back.

The name "act" comes from nektos/act, an open-source tool originally built to run GitHub Actions locally. Gitea forked and adapted it into their runner, so act_runner is a lineage artifact — the binary keeps the upstream name, but everything else in our infrastructure uses gitea-runner.

How it works

1. The runner daemon polls the Gitea instance for queued workflow jobs
2. When a job is picked up, the runner pulls the Docker image specified by the workflow label (e.g., ubuntu-24.04 maps to docker.gitea.com/runner-images:ubuntu-24.04)
3. Each workflow step executes inside an ephemeral container
4. Logs and status are streamed back to Gitea in real time
5. The container is destroyed after the job completes

Architecture in Agathos

Gitea (Rosalind)                    Act Runner (Puck)
┌──────────────┐    poll/report     ┌──────────────────┐
│ gitea.ouranos │◄──────────────────│ act_runner daemon │
│ .helu.ca     │                    │ (gitea-runner)    │
└──────────────┘                    └────────┬─────────┘
                                             │ spawns
                                    ┌────────▼─────────┐
                                    │  Docker containers │
                                    │  (workflow steps)  │
                                    └──────────────────┘

Naming conventions

The binary is act_runner — that's the upstream package name and renaming it would break updates. Everything else uses gitea-runner:

Component	Name
Binary	/usr/local/bin/act_runner (upstream, don't rename)
Service account	gitea-runner
Home directory	/srv/gitea-runner/
Config file	/srv/gitea-runner/config.yaml
Registration state	/srv/gitea-runner/.runner (created by registration)
Systemd service	gitea-runner.service
Runner name	puck-runner (shown in Gitea UI)

---

Ansible Deployment

The runner is deployed via the gitea_runner Ansible service to Puck (application runtime host with Docker already available).

Prerequisites

• Docker must be installed on the target host (docker in services list)
• Gitea must be running and accessible at https://gitea.ouranos.helu.ca

Deploy

# Deploy to all hosts with gitea_runner in their services list
ansible-playbook gitea_runner/deploy.yml

# Dry run (skip registration prompt)
ansible-playbook gitea_runner/deploy.yml --check

# Limit to a specific host
ansible-playbook gitea_runner/deploy.yml --limit puck.incus

# Non-interactive mode (for CI/CD)
ansible-playbook gitea_runner/deploy.yml -e registration_token=YOUR_TOKEN

The playbook is also included in the full-stack deployment via site.yml, running after the Gitea playbook.

Registration Prompt: On first deployment, the playbook will pause and prompt for a registration token. Get the token from https://gitea.ouranos.helu.ca/-/admin/runners before running the playbook.

What the playbook does

1. Filters hosts — only runs on hosts with gitea_runner in their services list
2. Creates gitea-runner system group and user (added to docker group)
3. Downloads act_runner binary from Gitea releases (version pinned as act_runner_version in group_vars/all/vars.yml)
4. Skips download if the installed version already matches (idempotent)
5. Copies the managed config.yaml from the Ansible controller (edit ansible/gitea_runner/config.yaml to change runner settings)
6. Templates gitea-runner.service systemd unit
7. Registers the runner — prompts for registration token on first deployment
8. Enables and starts the service

Systemd unit

# /etc/systemd/system/gitea-runner.service
[Unit]
Description=Gitea Runner
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=gitea-runner
Group=gitea-runner
WorkingDirectory=/srv/gitea-runner
ExecStart=/usr/local/bin/act_runner daemon --config /srv/gitea-runner/config.yaml
Restart=on-failure
RestartSec=10
Environment=HOME=/srv/gitea-runner

[Install]
WantedBy=multi-user.target

Registration Flow

On first deployment, the playbook will automatically prompt for a registration token:

TASK [Prompt for registration token]

Gitea runner registration required.
Get token from: https://gitea.ouranos.helu.ca/-/admin/runners

Enter registration token:
[Enter token here]

Steps:

1. Before running the playbook, obtain a registration token:
   • Navigate to https://gitea.ouranos.helu.ca/-/admin/runners
   • Click "Create new Runner"
   • Copy the displayed token
2. Run the deployment playbook
3. Paste the token when prompted

The registration is idempotent — if the runner is already registered (.runner file exists), the prompt is skipped.

Non-interactive mode: Pass the token as an extra variable:

ansible-playbook gitea_runner/deploy.yml -e registration_token=YOUR_TOKEN

Manual registration (if needed): The traditional method still works if you prefer manual control. Labels are picked up from config.yaml at daemon start, so --labels is not needed at registration:

ssh puck.incus
sudo -iu gitea-runner
act_runner register \
  --instance https://gitea.ouranos.helu.ca \
  --token <token> \
  --name puck-runner \
  --no-interactive

Verify

# Check service status
sudo systemctl status gitea-runner

# Check runner version
act_runner --version

# View runner logs
sudo journalctl -u gitea-runner -f

puck-runner should show as online at https://gitea.ouranos.helu.ca/-/admin/runners.

Runner labels

Labels map workflow runs-on values to Docker images. They are configured in ansible/gitea_runner/config.yaml under runner.labels:

Label	Docker Image	Use case
ubuntu-latest	docker.gitea.com/runner-images:ubuntu-latest	General CI (Gitea official image)
ubuntu-24.04	docker.gitea.com/runner-images:ubuntu-24.04	Ubuntu 24.04 builds
ubuntu-22.04	docker.gitea.com/runner-images:ubuntu-22.04	Ubuntu 22.04 builds
ubuntu-20.04	docker.gitea.com/runner-images:ubuntu-20.04	Ubuntu 20.04 builds
node-24	node:24-bookworm	Node.js CI

To add or change labels, edit ansible/gitea_runner/config.yaml and re-run the playbook.

Configuration reference

Variable	Location	Value
act_runner_version	group_vars/all/vars.yml	0.2.13
gitea_runner_instance_url	group_vars/all/vars.yml	https://gitea.ouranos.helu.ca
gitea_runner_name	host_vars/puck.incus.yml	puck-runner
Runner labels	ansible/gitea_runner/config.yaml	See runner.labels section

Upgrading

To upgrade the runner binary, update act_runner_version in group_vars/all/vars.yml and re-run the playbook:

# Edit the version
vim inventory/group_vars/all/vars.yml
# act_runner_version: "0.2.14"

# Re-deploy — only the binary download and service restart will trigger
ansible-playbook gitea_runner/deploy.yml