The runner connects outbound to a Gitea instance, picks up Actions jobs and runs them as Docker containers. It exposes no web endpoint, so it is not routed through Traefik and needs no DOMAIN or TLS certificate. You still pass a --domain to abra app new — it only names the app on disk, it is not a routed web address.

Category: Development
Status: 1, alpha
Image: gitea/act_runner, 4, upstream
Healthcheck: Yes
Backups: N/A (state is re-registerable)
Email: N/A
Tests: No
SSO: N/A

⚠️ Security: host Docker socket

This recipe mounts the host Docker socket (/var/run/docker.sock) into the runner so it can start job containers as siblings on the host daemon. CI jobs therefore have effective control of the host's Docker daemon — run this on a dedicated runner host, not a shared multi-tenant swarm.

Docker-in-Docker (dind) is not offered as an alternative: abra deploys via docker stack deploy, and Docker Swarm silently ignores privileged: true, which docker:dind requires to start its inner daemon.

Quick start

1. Get a registration token

In your Gitea instance, go to Actions → Runners → Create new runner and copy the token. Runners can be registered at three levels:

Level	Settings page
Instance	`https://git.example.com/-/admin/actions/runners`
Organisation	`https://git.example.com/<org>/settings/actions/runners`
Repository	`https://git.example.com/<owner>/<repo>/settings/actions/runners`

2. Deploy

abra app new gitea-runner --domain gitea-runner.example.com

# set GITEA_INSTANCE_URL, RUNNER_NAME, RUNNER_LABELS
abra app config gitea-runner.example.com

# store the registration token as a secret
abra app secret insert gitea-runner.example.com reg_token v1 "<TOKEN>"

abra app deploy gitea-runner.example.com

The runner auto-registers on first start using GITEA_INSTANCE_URL and the reg_token secret. Confirm it worked:

abra app logs gitea-runner.example.com          # look for "runner registered successfully"

The runner then appears as Idle / Online under Actions → Runners in Gitea.

Managing the runner

Helper functions live in abra.sh and are invoked with abra app cmd:

# show the registration state (.runner file)
abra app cmd gitea-runner.example.com app status

# force (re-)registration, e.g. after rotating the token secret
abra app cmd gitea-runner.example.com app register

# print a default config.yaml for reference/customising
abra app cmd gitea-runner.example.com app generate_config

The same actions with raw commands via abra app run:

abra app run gitea-runner.example.com app -- cat /data/.runner

abra app run gitea-runner.example.com app -- act_runner register --no-interactive \
    --instance https://git.example.com \
    --token <TOKEN> \
    --name coopcloud-runner \
    --labels "ubuntu-latest:docker://catthehacker/ubuntu:act-latest" \
    --config /config.yaml

# list job containers the runner has spawned on the host
abra app run gitea-runner.example.com app -- docker ps

Configuration

Set in the app's .env (abra app config <domain>):

Variable	Purpose
`GITEA_INSTANCE_URL`	URL of the Gitea instance (scheme, no trailing path)
`RUNNER_NAME`	Name shown in the Gitea runner list
`RUNNER_LABELS`	Comma-separated labels (e.g. `ubuntu-latest:docker://catthehacker/ubuntu:act-latest`) advertising what the runner provides
`RUNNER_CAPACITY`	Concurrent jobs per runner (default `1`)
`LOG_LEVEL`	act_runner log level (default `info`)

Labels are read at registration time. After changing RUNNER_LABELS, re-run abra app cmd <domain> app register (or reset the runner in Gitea and rotate the token) for the change to take effect.

Finer-grained tuning lives in config.yaml.tmpl (rendered as a swarm config); bump CONFIG_VERSION in abra.sh when you change it.