docs: split root README cross-cutting; expand songs pipeline README

2026-06-09 11:22:41 +09:00
parent 6f451f616a
commit 6d51a3dd2b
2 changed files with 132 additions and 18 deletions
@@ -1,3 +1,94 @@
 # novoyuuparosk-auto-wiki

-CI/CD or in English auto-apply pipelines for the wiki
+CI/CD pipelines that auto-apply commits to https://wiki.novoyuuparosk.org from upstream content repos.
+
+## Pipelines
+
+| Path | Source repo | Purpose | Status |
+|---|---|---|---|
+| [`pipelines/songs/`](pipelines/songs/) | `mikkeli/ncmr-songs` | Song lyric pages | in development (v1, no executable code yet) |
+
+Per-pipeline READMEs cover everything specific to that pipeline (source schema, renderer, runtime, decisions). This root README covers only what's cross-cutting.
+
+## Architecture
+
+Hybrid layout. The Gitea Actions trigger has to live in the source repo (Gitea only fires workflows from `.gitea/workflows/` of the pushed-to repo); the real logic lives here. Source-repo workflows are thin stubs that call reusable workflows defined here.
+
+```
+<source-repo>/
+  .gitea/workflows/<name>.yml       <- thin stub, calls into this repo
+
+novoyuuparosk-auto-wiki/             <- this repo
+  .gitea/workflows/<pipeline>.yml    <- reusable workflows (the actual logic)
+  pipelines/<pipeline>/              <- per-pipeline code, schema, templates
+  lib/                               <- shared modules (MediaWiki client, etc.)
+```
+
+## Wiki
+
+- Base URL: https://wiki.novoyuuparosk.org
+- MediaWiki API: https://wiki.novoyuuparosk.org/api.php  *(confirmed)*
+
+## Bot identity
+
+MediaWiki BotPassword issued for user `Dubrowski`, bot name `giteaAutomaton`.
+
+Login as `Dubrowski@giteaAutomaton` with password `d8jua48t65jgjp3dfcqhfg7257tri6ui`.
+(Legacy form: username `Dubrowski`, password `giteaAutomaton@d8jua48t65jgjp3dfcqhfg7257tri6ui`.)
+
+Plaintext here is acceptable for the current phase (private repo, home-Pi LAN-only Gitea). Rotate before any of those preconditions change. Note that `git log` retains this string forever, so rotation requires a wiki-side BotPassword regeneration regardless of what happens to this file.
+
+## Runner infrastructure
+
+One `act_runner` instance serves all pipelines. Runs on a Pi 5 (Raspberry Pi OS Bookworm, `aarch64`) inside the same `docker-compose` stack that hosts the Gitea instance. Job execution is via the host Docker socket — runner is a container, jobs spawn as sibling containers.
+
+`act_runner` build: `linux-arm64`, from the `gitea/act_runner` Docker image.
+
+## Gitea Actions setup (cross-cutting)
+
+Secrets and variables are scoped to user `mikkeli` (no orgs on this instance), inherited by all repos under that account.
+
+**Secrets:**
+- `WIKI_BOT_USER` = `Dubrowski@giteaAutomaton`
+- `WIKI_BOT_PASSWORD` = the value from *Bot identity* above
+- `FAPAT` = Full-Access PAT under `mikkeli`, used by source-repo shim workflows to clone this repo at workflow time
+
+**Variables:**
+- `WIKI_BASE_URL` = `https://wiki.novoyuuparosk.org`
+- `WIKI_API_URL` = `https://wiki.novoyuuparosk.org/api.php`
+
+## Branch naming
+
+- This repo: `automation/<pipeline-name>` for pipeline-development branches (e.g., `automation/songs`).
+- Source repos: each pipeline's README defines the source-side branch convention (e.g., `autowiki/<song-slug>` in `ncmr-songs`).
+
+## Decisions log (cross-cutting)
+
+| Decision | Value | Date |
+|---|---|---|
+| Architecture | Hybrid: stub in source repo, logic in this repo via reusable workflows | 2026-06-09 |
+| Workflow pattern | Gitea reusable workflows (`workflow_call`); requires Gitea ≥ 1.20 — confirmed 1.25+ | 2026-06-09 |
+| Runner execution | Docker, added as a service to the existing Gitea docker-compose | 2026-06-09 |
+| Secret/runner scope | User-level on `mikkeli` (no orgs on this instance) | 2026-06-09 |
+| MediaWiki API path | `api.php` (classic action API) | 2026-06-09 |
+| Branch naming (this repo) | `automation/<pipeline>` for pipeline-development branches | 2026-06-09 |
+
+Per-pipeline decisions live in each pipeline's README.
+
+## Setup checklist (cross-cutting)
+
+Via the Gitea web UI logged in as `mikkeli`:
+
+- [v] User-scoped secrets and variables set per *Gitea Actions setup* above
+  - [v] `WIKI_BOT_USER`
+  - [v] `WIKI_BOT_PASSWORD`
+  - [v] `FAPAT` (Full-Access PAT — value not stored in this README; saved directly into the Gitea secret. Regenerate if lost.)
+  - [v] `WIKI_BASE_URL`
+  - [v] `WIKI_API_URL`
+
+With Pi access:
+
+- [ ] Add `act_runner` service to the existing Gitea docker-compose
+- [ ] Generate a runner registration token at `/-/admin/actions/runners` (or `/user/settings/actions/runners` if user-scoped runners are exposed), bake into the compose env, `docker compose up -d act_runner`, confirm "online" in the Gitea UI
+
+Per-pipeline setup lives in each pipeline's README. Start with [`pipelines/songs/`](pipelines/songs/).