From 6d51a3dd2bf780da656185c00d98479527014fba Mon Sep 17 00:00:00 2001 From: Wan Ziyu Date: Tue, 9 Jun 2026 11:22:41 +0900 Subject: [PATCH] docs: split root README cross-cutting; expand songs pipeline README --- README.md | 93 ++++++++++++++++++++++++++++++++++++++- pipelines/songs/README.md | 57 +++++++++++++++++------- 2 files changed, 132 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index ef3da0e..adeef8e 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,94 @@ # novoyuuparosk-auto-wiki -CI/CD or in English auto-apply pipelines for the wiki \ No newline at end of file +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. + +``` +/ + .gitea/workflows/.yml <- thin stub, calls into this repo + +novoyuuparosk-auto-wiki/ <- this repo + .gitea/workflows/.yml <- reusable workflows (the actual logic) + pipelines// <- 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/` for pipeline-development branches (e.g., `automation/songs`). +- Source repos: each pipeline's README defines the source-side branch convention (e.g., `autowiki/` 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/` 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/). diff --git a/pipelines/songs/README.md b/pipelines/songs/README.md index 5de76b3..5c0af42 100644 --- a/pipelines/songs/README.md +++ b/pipelines/songs/README.md @@ -2,7 +2,8 @@ Publishes lyric pages from `mikkeli/ncmr-songs` to `https://wiki.novoyuuparosk.org`. -For the source-file contract (frontmatter and body conventions), see [SCHEMA.md](SCHEMA.md). This README covers the pipeline implementation and its runtime. +- Source-file contract (frontmatter and body conventions): [SCHEMA.md](SCHEMA.md) +- Cross-cutting setup (wiki URL, bot identity, runner, Gitea secrets/variables): [repo root README](../../README.md) ## v1 scope @@ -21,21 +22,32 @@ Deferred (schema reserves the fields; renderer doesn't yet act on them): - Multi-language metadata (the body conveys what languages exist; renderer doesn't introspect) - Auto-generated album index pages (intentionally NOT done — user writes album category-page descriptions freeform) +## Source repo and branch convention + +Source repo: `mikkeli/ncmr-songs`. The pipeline triggers on push to `master`. + +**Branch convention in `ncmr-songs`**: per-song short-lived branches named `autowiki/` (e.g., `autowiki/pulse`). Create when staging edits, merge to master when ready to publish, delete after one cycle. + +**Excluded paths** (won't trigger the pipeline): + +- `wip/**` +- `README.md`, `.gitignore`, `.claude/**` + ## Invocation -The pipeline is invoked via a reusable Gitea Actions workflow (`/.gitea/workflows/publish-songs.yml` in this repo). The `ncmr-songs` repo holds a thin stub workflow that calls into this one on push to `master`. +The pipeline is invoked via a reusable Gitea Actions workflow (`.gitea/workflows/publish-songs.yml` in this repo). The `ncmr-songs` repo holds a thin stub workflow (`.gitea/workflows/publish.yml`) that calls into this one on push to `master`. -Required environment at runtime: +### Workflow inputs and secrets -| Variable | Source | Purpose | -|---|---|---| -| `WIKI_API_URL` | Gitea variable | MediaWiki action API endpoint | -| `WIKI_BASE_URL` | Gitea variable | Wiki base URL (used in the banner link) | -| `WIKI_BOT_USER` | Gitea secret | Bot login (`Dubrowski@giteaAutomaton`) | -| `WIKI_BOT_PASSWORD` | Gitea secret | BotPasswords value | -| `SOURCE_DIR` | workflow input | Path to checked-out `ncmr-songs` working tree | -| `SOURCE_REF` | workflow input | The pushed-to commit SHA | -| `SOURCE_BASE_REF` | workflow input | The SHA prior to the push (for diff-based change detection) | +| Name | Kind | Source | Purpose | +|---|---|---|---| +| `WIKI_API_URL` | variable | Gitea (cross-cutting) | MediaWiki action API endpoint | +| `WIKI_BASE_URL` | variable | Gitea (cross-cutting) | Wiki base URL (used in the banner link) | +| `WIKI_BOT_USER` | secret | Gitea (cross-cutting) | Bot login | +| `WIKI_BOT_PASSWORD` | secret | Gitea (cross-cutting) | BotPasswords value | +| `SOURCE_DIR` | workflow input | from the stub | Path to checked-out `ncmr-songs` working tree | +| `SOURCE_REF` | workflow input | from the stub | The pushed-to commit SHA | +| `SOURCE_BASE_REF` | workflow input | from the stub | The SHA prior to the push (for diff-based change detection) | ## Dependencies @@ -56,11 +68,22 @@ Before the first run, two things must exist on the wiki: ## Modes -The pipeline supports two invocation modes via the entry point: - -- **Incremental** (default, triggered by push): publishes only files changed between `SOURCE_BASE_REF` and `SOURCE_REF`. +- **Incremental** (default, triggered by push to `master`): publishes only files changed between `SOURCE_BASE_REF` and `SOURCE_REF`. - **Full** (`--all` flag, triggered by `workflow_dispatch`): re-publishes every publishable file in the source tree. Use after template or renderer changes. -## Not yet implemented +## Decisions log (songs pipeline) -This README will grow as the pipeline does. Current commit ships only the schema and this overview — no executable code yet. +| Decision | Value | Date | +|---|---|---| +| Metadata source | YAML frontmatter inside each `.md` (see [SCHEMA.md](SCHEMA.md)) | 2026-06-09 | +| Body rendering | Pandoc-based, with a thin Python pre/post-processor | 2026-06-09 | +| Excluded paths | `wip/**`, plus repo-meta files | 2026-06-09 | +| Page template | Designed from scratch (no existing wiki pages to mirror) | 2026-06-09 | +| Album landing pages | Auto-injected `[[Category:]]`; the wiki category page is user-written and not overwritten by the pipeline | 2026-06-09 | +| Source-repo branch convention | `autowiki/` short-lived branches in `ncmr-songs` | 2026-06-09 | + +## Status + +Schema and pipeline overview committed. No executable code yet. + +**Next**: implement renderer (Python module), workflow YAMLs (this repo + `ncmr-songs` stub), `Template:Auto-generated` wikitext, and end-to-end dry-run on `ses/pulse.md`.