Document how a repository opts in to wiki publishing
Validate workflows / validate (pull_request) Successful in 16s

Describe the wiki/.publish marker and the prune word, the per-organisation
TOKEN_FOR_GITEA_WIKI without fallback, and the new messages in the
onboarding, credentials and troubleshooting guides and the README. Add the
capability row and regenerate the five English wiki pages with their Danish
and Bahasa Malaysia translations.

Task: MIL-006#5
This commit is contained in:
2026-10-10 11:54:54 +08:00
parent e530ecd99d
commit de2e28e637
19 changed files with 158 additions and 56 deletions
+14 -12
View File
@@ -56,27 +56,29 @@ is ever printed.
## Wiki publishing secret
The workflow **Publish wiki** (this repository only) copies `wiki/` to the Gitea
wiki when a change to `wiki/` is merged to `main`. It uses `TOKEN_FOR_GITEA_WIKI`
when that secret exists and otherwise reuses `TOKEN_FOR_GITEA`.
The workflow **Publish wiki** copies `wiki/` to the Gitea wiki of a repository
that has opted in with `wiki/.publish` (see [onboarding.md](onboarding.md)). It
uses its own secret, so the metadata sync token stays read-only.
| Secret | Content | Used for |
| --- | --- | --- |
| `TOKEN_FOR_GITEA_WIKI` (optional) | The Gitea token, nothing else | Writing the wiki pages of this repository |
| `TOKEN_FOR_GITEA_WIKI` | The Gitea token, nothing else | Writing the wiki pages of the repositories of an organization that opt in |
- The token that is used needs scope `write:repository`, and its user needs
write access to this repository. Gitea has no wiki-only scope.
- `TOKEN_FOR_GITEA` is documented above with `read:repository` only. Reusing it
for the wiki means raising its scope, which also gives the metadata sync
write access. A separate `TOKEN_FOR_GITEA_WIKI` for a dedicated user keeps
the sync token read-only. S05 decides which, and S03 stores the secret.
- Store it as a secret of the organization of each repository that publishes.
There is no fallback to `TOKEN_FOR_GITEA`: a repository that opted in and has
no such secret fails with a configuration error, and a repository that did
not opt in does not need it.
- The token needs scope `write:repository`, and its user needs write access to
the repositories. Gitea has no wiki-only scope, so create the token for a
dedicated user. S05 approves the scope and S03 stores the secret.
- Calls made: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`,
`GET`, `POST` and `PATCH /repos/{owner}/{repo}/wiki/...` and, for a page that
no longer exists in `wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}`.
- The wiki must be enabled in the repository settings. The workflow refuses to
run when it is not.
- The wiki always equals `wiki/`: pages edited or added in the Gitea web UI are
overwritten or removed on the next publish.
- Pages that are in `wiki/` are always overwritten from it, so a change made
in the Gitea web UI is lost on the next publish. Pages that are only in the
wiki are removed only when `wiki/.publish` contains the word `prune`.
## Rotating a token