Gitea Actions: act_runner install, register, and workflows
==========================================================

This guide covers connecting a self-hosted act_runner to Gitea (same engine as
GitHub Actions-style workflows), binary download, registration, optional YAML
runner config, and a repository workflow example.

Official reference:
  https://docs.gitea.com/usage/actions/act-runner

act_runner project:
  https://gitea.com/gitea/act_runner


Prerequisites
-------------

- Gitea 1.19+ with Actions enabled (server and repo/org settings as needed).
- For Docker-based jobs (default labels like ubuntu-latest): Docker Engine
  installed and running on the runner host, and the user running act_runner in
  the docker group (Linux) or equivalent.
- Network from the runner to your Gitea HTTP(S) URL.


1. Download the binary (Linux amd64, version 0.2.11)
-----------------------------------------------------

Use one consistent filename end-to-end (avoid mixing act_runner and
act_runner-linux-amd64):

  cd /opt/act_runner
  sudo mkdir -p /opt/act_runner && sudo chown "$USER": /opt/act_runner
  cd /opt/act_runner

  wget https://dl.gitea.com/act_runner/0.2.11/act_runner-0.2.11-linux-amd64 -O act_runner
  chmod +x act_runner
  ./act_runner --version

Other platforms and versions:
  https://gitea.com/gitea/act_runner/releases
  https://dl.gitea.com/act_runner/


2. Get a registration token from Gitea
--------------------------------------

Runners can be registered at instance, organization, or repository scope.

  Instance (admin): Site Administration -> Actions -> Runners
    (path like /-/admin/actions/runners)

  Organization:     Org -> Settings -> Actions -> Runners

  Repository:       Repo -> Settings -> Actions -> Runners

Alternative on the Gitea server:

  gitea --config /etc/gitea/app.ini actions generate-runner-token

CLI docs:
  https://docs.gitea.com/administration/command-line#actions-generate-runner-token


3. Register the runner
----------------------

Interactive (prompts for instance URL, token, name, labels):

  ./act_runner register

  or

  ./act_runner --config config.yaml register

Non-interactive (automation / CI):

  ./act_runner register --no-interactive \
    --instance "https://gitea.example.com/" \
    --token "YOUR_REGISTRATION_TOKEN" \
    --name "my-runner-01" \
    --labels "ubuntu-latest:docker://gitea/runner-images:ubuntu-latest"

After registration, a .runner file appears in the working directory (or path
set in config). Back up this file; do not commit secrets. If it is lost, remove
it and register again with a new token if needed.


4. Start the runner
-------------------

Foreground:

  ./act_runner daemon

  or

  ./act_runner daemon --config config.yaml

systemd example (paths adjusted to your install):

  [Unit]
  Description=Gitea Actions runner
  After=docker.service

  [Service]
  ExecStart=/opt/act_runner/act_runner daemon --config /opt/act_runner/config.yaml
  WorkingDirectory=/opt/act_runner
  Restart=always
  User=act_runner
  Group=docker

  [Install]
  WantedBy=multi-user.target

Then:

  sudo systemctl daemon-reload && sudo systemctl enable --now act_runner


5. Repository workflow YAML (Gitea Actions)
-------------------------------------------

Workflows live under .gitea/workflows/ (not .github/workflows unless your
Gitea is configured to use that path). Use runs-on labels that match your
runner (defaults include ubuntu-latest).

Example workflow file in this repo:
  .gitea/workflows/ci-example.yml


Quick checklist
---------------

1. wget ... chmod +x ... ./act_runner --version
2. Token from Settings -> Actions -> Runners (or admin/org/repo equivalent)
3. ./act_runner register (or --non-interactive ...)
4. ./act_runner daemon
5. Commit a workflow under .gitea/workflows/ and push


Docker image alternative
------------------------

If you prefer the official image instead of the bare binary:

  docker run -d \
    -e GITEA_INSTANCE_URL="https://gitea.example.com/" \
    -e GITEA_RUNNER_REGISTRATION_TOKEN="YOUR_REGISTRATION_TOKEN" \
    -e GITEA_RUNNER_NAME="docker-runner-01" \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v "$PWD/data:/data" \
    --name gitea_act_runner \
    docker.io/gitea/act_runner:latest

Persist the /data volume so the runner does not re-register on every restart.


Version note
------------

Ephemeral runners and some flags require act_runner 0.2.12+. This document uses
0.2.11 for the download URL; upgrade the URL when you bump versions.