From d441e3862df5950d2a500edafda29ce353669ba6 Mon Sep 17 00:00:00 2001 From: bot-hermes Date: Mon, 10 Aug 2026 09:13:00 +0000 Subject: [PATCH] docs(deploy): add one-time Gitea Actions runner setup steps The CI workflow (projecte-runner) was never registered on the Gitea instance, leaving quality/e2e/deploy/smoke jobs stuck at 'Waiting to run'. Document the act_runner install/register/start flow so the pipeline can be unblocked from the deploy host. --- DEPLOY.md | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/DEPLOY.md b/DEPLOY.md index e3b4048..d91bc29 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -29,7 +29,7 @@ All services share the `project-e-network` bridge and restart unless stopped. ## CI/CD pipeline (Gitea Actions) -The workflow lives at `.gitea/workflows/ci.yml` and runs on the self-hosted runner `projecte-runner`, which is colocated with the deploy host. +The workflow lives at `.gitea/workflows/ci.yml` and runs on the self-hosted runner `projecte-runner`, which is colocated with the deploy host. The runner must be registered once (see "Setting up the runner" below) before any job can run. - **`quality`** — runs on every push and pull request: `bun install --frozen-lockfile` → `bun run typecheck` → web build (`cd apps/web && bun run build`) → `docker compose build`. A failed quality gate blocks the deploy job. - **`deploy`** — runs on pushes to `main` and on `workflow_dispatch`. It checks out the code and runs `bash script/deploy.sh` with `DEPLOY_DIR` defaulting to `/home/projecte/ProjectE`. @@ -46,6 +46,41 @@ Idempotent, safe to re-run. It: 5. Runs `docker compose build` and `docker compose up -d` 6. Waits up to 60s for `http://localhost:3000/api/health` to return HTTP 200, dumping recent API logs if it times out +### Setting up the runner (one-time) + +The workflow runs on the self-hosted runner `projecte-runner`, which must be +registered on the Gitea instance before any job can start (otherwise jobs stay +stuck at "Waiting to run"). Do this once on the deploy host (10.0.0.204), which +is where the `deploy` and `smoke` jobs act on the local docker-compose stack: + +1. **Install `act_runner`** — download the `act_runner` binary from the Gitea + Releases page matching your server version, or use the official + `gitea/act_runner` Docker image. (Gitea Actions uses `act_runner`; the exact + binary/URL depends on your Gitea version.) +2. **Create a registration token** — in the Gitea web UI go to + **Repository → Settings → Actions → Runners → Create new runner** and copy + the token. +3. **Register** with a label that matches the workflow's `runs-on`: + + ```bash + ./act_runner register \ + --instance https://git.buzzbee.dev \ + --token \ + --name projecte-runner \ + --labels projecte-runner:host + ``` + + The label name `projecte-runner` must match `.gitea/workflows/ci.yml`; the + executor (`host` or `docker`) is your choice — `host` is simplest for a + single colocated runner. +4. **Start it** — run `./act_runner daemon` (or install it as a systemd service + so it survives reboots). + +**Verify:** the Runners page shows it online, then re-trigger the pipeline (a +push to `main`, or "Re-run" on the Actions tab). The `quality` job should leave +"Waiting to run". If jobs stay queued, the runner is offline or its label does +not match `runs-on: projecte-runner` — check the `act_runner` logs. + ## Secrets Secrets live in the host `.env` at `/home/projecte/ProjectE/.env`. This file is gitignored; never commit it. To set it up: