act runner setup doc is added

2026-04-28 18:01:52 +05:30
commit a489e1b9a4
1 changed files with 162 additions and 0 deletions
@@ -0,0 +1,162 @@
+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.