docs: rewrite README with structured overview and quick start guide
Replaces the minimal project description with a comprehensive README including a component overview table, quick start instructions, common Ansible operations, and links to detailed documentation. Aligns with Red Panda Approval™ standards.
This commit is contained in:
200
docs/gitea_runner.md
Normal file
200
docs/gitea_runner.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# 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](https://github.com/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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```ini
|
||||
# /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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
ssh puck.incus
|
||||
sudo -iu gitea-runner
|
||||
act_runner register \
|
||||
--instance https://gitea.ouranos.helu.ca \
|
||||
--token <token> \
|
||||
--name puck-runner \
|
||||
--no-interactive
|
||||
```
|
||||
|
||||
### Verify
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user