From d05ed3c5151f760f5ea12852c140754b3ad1c9da Mon Sep 17 00:00:00 2001 From: Zsolt Tasnadi Date: Thu, 6 Aug 2026 16:31:28 +0200 Subject: [PATCH] readme: woodpecker ci management --- README.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/README.md b/README.md index 5f5471d..9a3ebb3 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,10 @@ Repository: `https://git.teletypegames.org/tools/warp_engine` image library with orphan cleanup, a file manager with a picker mode, and download statistics. Without ActiveAdmin the engine runs headless (API + updater only). +- **Woodpecker CI management (optional)**: with a Woodpecker API token + configured, the admin also gains repo sync, a pipeline dashboard with + manual triggers, and automatic provisioning of application tokens as + Woodpecker secrets. ## Requirements @@ -285,6 +289,41 @@ an empty map (default) disables the feature. Set the Woodpecker side with per-repo in Settings → Extensions). Templates live in `app/services/warp_engine/platforms//pipeline.yaml.erb`. +## Woodpecker CI management + +Beyond serving pipeline configs, WarpEngine can drive the Woodpecker REST API +itself. Set `woodpecker_url` and `woodpecker_api_token` — while either is nil +(the default), every management feature stays inactive and the admin pages +hide themselves: + +```ruby +c.woodpecker_url = ENV["WOODPECKER_URL"] # e.g. "https://ci.example.org" +c.woodpecker_api_token = ENV["WOODPECKER_API_TOKEN"] # PAT of a Woodpecker *instance admin* +c.woodpecker_repo_owner = ENV["WOODPECKER_REPO_OWNER"] # forge org the game repos live under +``` + +What it unlocks (all surfaced in the admin): + +- **Repo sync** (*CI Repos → Sync from Woodpecker*): mirrors the Woodpecker + repo list into `CiRepository` records, auto-matching each repo to a catalog + `Software` by name; repos that disappear from Woodpecker are deactivated. + Platform and software links are editable by hand afterwards. +- **CI dashboard**: the latest pipeline status of every active repo, grouped + by platform, with a manual *Trigger* action; each repo's page lists its + recent pipelines. +- **Secret provisioning**: database application tokens are pushed to the + repos as the `application_token` Woodpecker secret — creating a token + provisions it to its owner's repos (unrestricted tokens to all active + repos), deleting a token removes the secret, and *Rotate* creates a + replacement token, provisions it everywhere and revokes the old one in a + single step. + +The API token must belong to a Woodpecker **instance admin** — listing the +server's repos is an admin-only endpoint (anything less yields +`403 User not authorized`). Add the user to `WOODPECKER_ADMIN` on the +Woodpecker server, then log out and back in: the admin flag is written to +the user record at login, a server restart alone is not enough. + ## Public API | Endpoint | Purpose |