TirSystem/github-action
0
1
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 8 Wiki Activity

Publish the wiki through a reusable workflow; this wiki moves to docs/wiki

Browse Source 
- publish-wiki-pages.yml: reusable workflow with wiki_dir, prune and
  tools-ref inputs and the declared secret TOKEN_FOR_GITEA_WIKI
- tools/publish_wiki.py: WIKI_PRUNE selects explicit mode without the marker;
  a missing folder is a configuration error
- publish-own-wiki.yml: this repository calls the reusable workflow
- wiki/ moves to docs/wiki/; build_wiki.py and its tests follow
- the scoped publish-wiki.yml is marked deprecated, not removed
- guides, README and the Danish and Bahasa Malaysia wiki pages describe the
  caller, docs/wiki/ and the new error messages

Task: MIL-008#2
Task: MIL-008#4
Task: MIL-008#5
Task: MIL-008#6
This commit is contained in:
Tirsvad
2026-10-13 22:20:10 +08:00
parent 01b9c2972b
commit 10e88e8a27
42 changed files with 826 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files
guides/credentials.md
+11 -10
View File
@@ -82,29 +82,30 @@ is ever printed.
## Wiki publishing secret
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.
The workflow **Publish wiki pages** copies `docs/wiki/` to the Gitea wiki of a
repository that calls it (see [onboarding.md](onboarding.md)). It uses its own
secret, so the metadata sync token stays read-only. The caller passes the
secret in `secrets:`; it is not inherited.
| Secret | Content | Used for |
| --- | --- | --- |
| `TOKEN_FOR_GITEA_WIKI` | The Gitea token, nothing else | Writing the wiki pages of the repositories of an organization that opt in |
- 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.
There is no fallback to `TOKEN_FOR_GITEA`: a repository that calls the
workflow and has no such secret fails with a configuration error, and a
repository that does not call it 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}`.
no longer exists in `docs/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.
- 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`.
- Pages that are in `docs/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 the call sets `prune: "true"`.
## Rotating a token
guides/onboarding.md
+30 -12
View File
@@ -45,25 +45,43 @@ Delivery is automatic, so a repository needs no copy of the workflow. Secrets ar
## Publish a wiki (optional)
The **Publish wiki** workflow copies the Markdown pages in `wiki/` to the
repository wiki when a change to `wiki/` is merged to `main`. It is delivered
like the sync workflow, but it writes only where a repository opts in.
The reusable workflow **Publish wiki pages** copies the Markdown pages in
`docs/wiki/` to the repository wiki when a change to `docs/wiki/` is merged to
`main`. The repository calls it, so nothing is written where no call exists.
The wiki has English and the product owner's language as a minimum.
1. Enable the wiki in the repository settings.
2. Add Markdown pages to `wiki/`. The file name is the page name: `Home.md` is
the home page. A hyphen in the name is a space in the page name: `Home-da.md`
is the page "Home da", and a link to it is `[Dansk](Home-da)`.
3. Add the marker `wiki/.publish`. Leave it empty to create and update pages
only. Put the single word `prune` in it to also delete wiki pages that are
not in `wiki/`, so the wiki always equals the folder.
2. Add Markdown pages to `docs/wiki/`. The file name is the page name: `Home.md`
is the home page. A hyphen in the name is a space in the page name:
`Home-da.md` is the page "Home da", and a link to it is `[Dansk](Home-da)`.
3. Add a workflow, for example `.gitea/workflows/publish-wiki.yml`, that calls
the reusable workflow:
```yaml
on:
push:
branches: [ main ]
paths: [ "docs/wiki/**" ]
jobs:
wiki:
uses: TirSystem/github-action/.gitea/workflows/publish-wiki-pages.yml@v1
with:
prune: "true"
secrets:
TOKEN_FOR_GITEA_WIKI: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
```
`wiki_dir` defaults to `docs/wiki`. `prune: "true"` also deletes wiki pages
that are not in the folder, so the wiki always equals the folder; the
default `false` keeps them.
4. Store `TOKEN_FOR_GITEA_WIKI` as a secret of the repository's organization,
using the scope in [credentials.md](credentials.md).
5. Merge the change to `main`. The log must end with `Published <n> page(s) to
the wiki of <owner>/<repo>`.
A repository without `wiki/.publish` is skipped with the line `No
wiki/.publish marker in <owner>/<repo>`: nothing is written and no secret is
needed.
A repository that still has the marker `wiki/.publish` is published by the
older scoped workflow, which is removed once every repository has a call.
Move the pages to `docs/wiki/` and add the call before that.
## Runners
guides/troubleshooting.md
+12 -8
View File
@@ -26,11 +26,13 @@ never starts, or stops before the step) is a **runner** problem.
| `TOKEN_FOR_GITEA is missing or empty.` | configuration | Add the secret |
| `Could not determine the Gitea source repository.` | configuration | The run has no repository name; report as a defect |
| `Expected at most one GitHub push mirror ... found N` | configuration | Keep one GitHub push mirror |
| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Wiki publishing only: the repository opted in with `wiki/.publish` but its organization has no such secret; store it (see [credentials.md](credentials.md)) |
| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Wiki publishing only: leave the marker empty, or put only the word `prune` in it |
| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Wiki publishing only: the repository calls the workflow but its organization has no such secret, or the call does not pass it; store it and pass it in `secrets:` (see [credentials.md](credentials.md)) |
| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Wiki publishing through the older scoped workflow only: leave the marker empty, or put only the word `prune` in it |
| `The prune input must be 'true' or 'false'` | configuration | Wiki publishing only: set `prune` in the call to `"true"` or `"false"` |
| `The wiki folder ... does not exist` | configuration | Wiki publishing only: set `wiki_dir` in the call to the folder with the pages (default `docs/wiki`) |
| `... HTTP 403 ...` while publishing the wiki | permissions | Wiki publishing only: the token needs `write:repository` and write access to this repository |
| `The wiki is not enabled on <repo>` | configuration | Wiki publishing only: enable the wiki in the repository settings |
| `The wiki source directory ... has no Markdown pages` | configuration | Wiki publishing only: `wiki/` is empty or missing; nothing was changed |
| `The wiki source directory ... has no Markdown pages` | configuration | Wiki publishing only: the folder has no Markdown pages; nothing was changed |
| `Could not determine the GitHub owner and repository ...` | configuration | The mirror address must look like `https://github.com/<owner>/<repo>.git` |
| `Gitea API request failed with HTTP 401` | credentials | Create a new Gitea token and update `TOKEN_FOR_GITEA` |
| `GitHub API request failed with HTTP 401` | credentials | Create a new GitHub token and update `PAT_FOR_GITHUB`; the value must be the token only (no name, quotes or JSON) |
@@ -53,12 +55,14 @@ synced.` The run succeeds but nothing was synced. Check that the Gitea
version supports the push mirror API and re-run.
`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for
this repository.` The Publish wiki run succeeds and writes nothing. The
repository has not opted in; add `wiki/.publish` if it should publish.
this repository.` The older scoped Publish wiki run succeeds and writes
nothing. The repository has not opted in; call the reusable workflow
**Publish wiki pages** (see [onboarding.md](onboarding.md)) if it should publish.
`<n> page(s) are in the wiki but not in wiki/ and were kept; put the word
'prune' in wiki/.publish to delete them.` The run succeeds. Pages that exist
only in the wiki are left alone unless the marker contains `prune`.
`<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune
input to true to delete them.` The run succeeds. Pages that exist only in the
wiki are left alone unless the call sets `prune: "true"` (with the older scoped
workflow: the word `prune` in `wiki/.publish`).
## Runner problems