diff --git a/README.md b/README.md index e8cb5cc..6292819 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ It currently contains the Gitea workflow [`sync-github-metadata.yml`](.gitea/sco - Repository secrets: - `TOKEN_FOR_GITEA`: Gitea API token (the token only, no JSON) - `PAT_FOR_GITHUB`: a GitHub personal access token allowed to edit the mirror repository (the token only, no JSON) - - `TOKEN_FOR_GITEA_WIKI` (optional, only in this repository, for the **Publish wiki** workflow): Gitea token that can write the repository wiki; when it is absent, `TOKEN_FOR_GITEA` is used and needs write access + - `TOKEN_FOR_GITEA_WIKI` (only for repositories that publish a wiki, see the [onboarding guide](guides/onboarding.md)): a Gitea token that can write the wiki, stored as a secret of the repository's organization; there is no fallback to `TOKEN_FOR_GITEA` ## 🛠️ Setup @@ -59,13 +59,14 @@ After a change to the sync workflow, also trigger **Sync GitHub mirror metadata* ## 🟢 Capabilities -Only the first row is implemented. The rest is planned and tracked in the [Project Plan](docs/project-plan.md), which also describes each use case. +Rows that say Implemented or Guides written exist today. The rest is planned and tracked in the [Project Plan](docs/project-plan.md), which also describes each use case. | Capability | Status | | --- | --- | | Synchronize repository metadata (Gitea to GitHub mirror) | Implemented in `.gitea/scoped_workflows/`, with offline tests and a validation workflow | | Configure and validate workflow credentials | Implemented for the sync workflow: preflight checks both tokens before any change ([guide](guides/credentials.md)) | | Onboard a repository, manage runners, diagnose failures | Guides written ([onboarding](guides/onboarding.md), [troubleshooting](guides/troubleshooting.md)); scoped delivery to other repositories not yet verified; brief use cases open (MIL-002) | +| Publish a repository wiki from `wiki/` (opt-in, delivered to every organization) | Implemented in `.gitea/scoped_workflows/publish-wiki.yml`, with offline tests; the pilot in a second repository is pending (MIL-006) | | Shared quality checks | Planned (MIL-003) | | Versioned release and publishing | Planned (MIL-004) | diff --git a/guides/credentials.md b/guides/credentials.md index 7186009..f23d0ba 100644 --- a/guides/credentials.md +++ b/guides/credentials.md @@ -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 diff --git a/guides/onboarding.md b/guides/onboarding.md index 1905018..571ebd6 100644 --- a/guides/onboarding.md +++ b/guides/onboarding.md @@ -43,6 +43,27 @@ Delivery is automatic, so a repository needs no copy of the workflow. Secrets ar and topics. 7. If it fails, use [troubleshooting.md](troubleshooting.md). +## 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. + +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. +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. +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 page(s) to + the wiki of /`. + +A repository without `wiki/.publish` is skipped with the line `No +wiki/.publish marker in /`: nothing is written and no secret is +needed. + ## Runners | Item | Value | diff --git a/guides/troubleshooting.md b/guides/troubleshooting.md index 4a1f082..a736d58 100644 --- a/guides/troubleshooting.md +++ b/guides/troubleshooting.md @@ -26,7 +26,8 @@ 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 | -| `No token for the wiki: set TOKEN_FOR_GITEA_WIKI, or TOKEN_FOR_GITEA.` | configuration | Wiki publishing only: add one of the secrets (see [credentials.md](credentials.md)) | +| `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 | | `... 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 ` | 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 | @@ -51,6 +52,14 @@ settings. 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 /; 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. + +` 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`. + ## Runner problems See the [Runners](onboarding.md#runners) section. In short: if the run stays diff --git a/wiki/Capabilities.da.md b/wiki/Capabilities.da.md index 33f1b10..3477233 100644 --- a/wiki/Capabilities.da.md +++ b/wiki/Capabilities.da.md @@ -1,4 +1,4 @@ - + > Dette er en oversættelse af [`Capabilities`](Capabilities). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres. @@ -6,13 +6,14 @@ ## Funktionalitet -Kun den første række er implementeret. Resten er planlagt og følges i [projektplanen](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md), som også beskriver hver enkelt use case. +Rækker, der siger Implementeret eller Vejledninger er skrevet, findes i dag. Resten er planlagt og følges i [projektplanen](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md), som også beskriver hver enkelt use case. | Funktionalitet | Status | | --- | --- | | Synkronisering af repositorymetadata (Gitea til GitHub-spejl) | Implementeret i `.gitea/scoped_workflows/`, med offline-tests og et valideringsworkflow | | Konfiguration og validering af workflow-credentials | Implementeret for synkroniseringsworkflowet: en forhåndskontrol tjekker begge tokens før enhver ændring ([vejledning](Credentials.da)) | | Tilslutning af et repository, administration af runners, fejlfinding | Vejledninger er skrevet ([tilslutning](Onboarding.da), [fejlfinding](Troubleshooting.da)); scoped levering til andre repositories er ikke verificeret endnu; korte use cases er åbne (MIL-002) | +| Publicering af et repositorys wiki fra `wiki/` (tilmelding, leveres til alle organisationer) | Implementeret i `.gitea/scoped_workflows/publish-wiki.yml`, med offline-tests; pilotforsøget i et andet repository afventer (MIL-006) | | Fælles kvalitetskontrol | Planlagt (MIL-003) | | Versioneret udgivelse og publicering | Planlagt (MIL-004) | diff --git a/wiki/Capabilities.md b/wiki/Capabilities.md index 83af824..e852e81 100644 --- a/wiki/Capabilities.md +++ b/wiki/Capabilities.md @@ -6,13 +6,14 @@ English | [Dansk](Capabilities.da) | [Bahasa Melayu](Capabilities.ms) ## Capabilities -Only the first row is implemented. The rest is planned and tracked in the [Project Plan](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md), which also describes each use case. +Rows that say Implemented or Guides written exist today. The rest is planned and tracked in the [Project Plan](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md), which also describes each use case. | Capability | Status | | --- | --- | | Synchronize repository metadata (Gitea to GitHub mirror) | Implemented in `.gitea/scoped_workflows/`, with offline tests and a validation workflow | | Configure and validate workflow credentials | Implemented for the sync workflow: preflight checks both tokens before any change ([guide](Credentials)) | | Onboard a repository, manage runners, diagnose failures | Guides written ([onboarding](Onboarding), [troubleshooting](Troubleshooting)); scoped delivery to other repositories not yet verified; brief use cases open (MIL-002) | +| Publish a repository wiki from `wiki/` (opt-in, delivered to every organization) | Implemented in `.gitea/scoped_workflows/publish-wiki.yml`, with offline tests; the pilot in a second repository is pending (MIL-006) | | Shared quality checks | Planned (MIL-003) | | Versioned release and publishing | Planned (MIL-004) | diff --git a/wiki/Capabilities.ms.md b/wiki/Capabilities.ms.md index 4ad1b76..0e31b6c 100644 --- a/wiki/Capabilities.ms.md +++ b/wiki/Capabilities.ms.md @@ -1,4 +1,4 @@ - + > Ini ialah terjemahan [`Capabilities`](Capabilities). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya. @@ -6,13 +6,14 @@ ## Keupayaan -Hanya baris pertama yang dilaksanakan. Selebihnya dirancang dan dijejaki dalam [Pelan Projek](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md), yang juga menerangkan setiap kes guna (use case). +Baris yang menyatakan Dilaksanakan atau Panduan telah ditulis wujud hari ini. Selebihnya dirancang dan dijejaki dalam [Pelan Projek](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md), yang juga menerangkan setiap kes guna (use case). | Keupayaan | Status | | --- | --- | | Menyegerakkan metadata repositori (Gitea ke cermin GitHub) | Dilaksanakan dalam `.gitea/scoped_workflows/`, dengan ujian luar talian dan aliran kerja pengesahan | | Mengkonfigur dan mengesahkan kelayakan (credentials) aliran kerja | Dilaksanakan untuk aliran kerja penyegerakan: semakan awal (preflight) memeriksa kedua-dua token sebelum sebarang perubahan ([panduan](Credentials.ms)) | | Menyertakan repositori, mengurus runner, mendiagnosis kegagalan | Panduan telah ditulis ([menyertakan repositori](Onboarding.ms), [diagnosis](Troubleshooting.ms)); penghantaran scoped ke repositori lain belum disahkan; use case ringkas masih terbuka (MIL-002) | +| Menerbitkan wiki repositori daripada `wiki/` (pilih menyertai, dihantar ke setiap organisasi) | Dilaksanakan dalam `.gitea/scoped_workflows/publish-wiki.yml`, dengan ujian luar talian; juruterbang dalam repositori kedua belum dibuat (MIL-006) | | Semakan kualiti bersama | Dirancang (MIL-003) | | Keluaran dan penerbitan berversi | Dirancang (MIL-004) | diff --git a/wiki/Credentials.da.md b/wiki/Credentials.da.md index 7a85c4e..651c1a8 100644 --- a/wiki/Credentials.da.md +++ b/wiki/Credentials.da.md @@ -1,4 +1,4 @@ - + > Dette er en oversættelse af [`Credentials`](Credentials). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres. @@ -48,17 +48,17 @@ Ved succes står der i loggen `Preflight passed: Gitea and GitHub accepted the c ## Secret til publicering af wiki -Workflowet **Publish wiki** (kun dette repository) kopierer `wiki/` til Gitea-wikien, når en ændring af `wiki/` flettes til `main`. Det bruger `TOKEN_FOR_GITEA_WIKI`, hvis den secret findes, og genbruger ellers `TOKEN_FOR_GITEA`. +Workflowet **Publish wiki** kopierer `wiki/` til Gitea-wikien i et repository, der har meldt sig til med `wiki/.publish` (se [onboarding.md](Onboarding.da)). Det bruger sin egen secret, så synkroniseringstokenet forbliver skrivebeskyttet. | Secret | Indhold | Bruges til | | --- | --- | --- | -| `TOKEN_FOR_GITEA_WIKI` (valgfri) | Gitea-tokenet, intet andet | At skrive wikisiderne for dette repository | +| `TOKEN_FOR_GITEA_WIKI` | Gitea-tokenet, intet andet | At skrive wikisiderne for de repositories i en organisation, der melder sig til | -- Det token, der bruges, skal have scope `write:repository`, og dets bruger skal have skriveadgang til dette repository. Gitea har intet scope kun til wikien. -- `TOKEN_FOR_GITEA` er beskrevet ovenfor med kun `read:repository`. Hvis det genbruges til wikien, skal dets scope hæves, hvilket også giver metadatasynkroniseringen skriveadgang. En separat `TOKEN_FOR_GITEA_WIKI` til en dedikeret bruger holder synkroniseringstokenet skrivebeskyttet. S05 beslutter hvilket, og S03 gemmer secreten. +- Gem den som en secret i organisationen for hvert repository, der publicerer. Der er ingen reserve til `TOKEN_FOR_GITEA`: et repository, der har meldt sig til og ikke har secreten, fejler med en konfigurationsfejl, og et repository, der ikke har meldt sig til, behøver den ikke. +- Tokenet skal have scope `write:repository`, og dets bruger skal have skriveadgang til repositories. Gitea har intet scope kun til wikien, så opret tokenet til en dedikeret bruger. S05 godkender scopet, og S03 gemmer secreten. - Kald, der foretages: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`, `GET`, `POST` og `PATCH /repos/{owner}/{repo}/wiki/...` og, for en side, der ikke længere findes i `wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}`. - Wikien skal være aktiveret i repositoryets indstillinger. Workflowet nægter at køre, hvis den ikke er det. -- Wikien er altid lig med `wiki/`: sider, der er redigeret eller tilføjet i Gitea's weboverflade, overskrives eller fjernes ved næste publicering. +- Sider, der findes i `wiki/`, overskrives altid fra den, så en ændring i Gitea's weboverflade går tabt ved næste publicering. Sider, der kun findes i wikien, fjernes kun, når `wiki/.publish` indeholder ordet `prune`. ## Udskiftning af et token diff --git a/wiki/Credentials.md b/wiki/Credentials.md index cecdc1a..b936c78 100644 --- a/wiki/Credentials.md +++ b/wiki/Credentials.md @@ -62,27 +62,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)). 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 diff --git a/wiki/Credentials.ms.md b/wiki/Credentials.ms.md index 751f7f7..3771556 100644 --- a/wiki/Credentials.ms.md +++ b/wiki/Credentials.ms.md @@ -1,4 +1,4 @@ - + > Ini ialah terjemahan [`Credentials`](Credentials). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya. @@ -48,17 +48,17 @@ Apabila berjaya, log menyatakan `Preflight passed: Gitea and GitHub accepted the ## Secret untuk menerbitkan wiki -Aliran kerja **Publish wiki** (repositori ini sahaja) menyalin `wiki/` ke wiki Gitea apabila perubahan pada `wiki/` digabungkan ke `main`. Ia menggunakan `TOKEN_FOR_GITEA_WIKI` jika secret itu wujud, dan jika tidak, menggunakan semula `TOKEN_FOR_GITEA`. +Aliran kerja **Publish wiki** menyalin `wiki/` ke wiki Gitea bagi repositori yang telah memilih menyertainya dengan `wiki/.publish` (lihat [onboarding.md](Onboarding.ms)). Ia menggunakan secret sendiri, supaya token penyegerakan metadata kekal baca sahaja. | Secret | Kandungan | Digunakan untuk | | --- | --- | --- | -| `TOKEN_FOR_GITEA_WIKI` (pilihan) | Token Gitea, tiada yang lain | Menulis halaman wiki repositori ini | +| `TOKEN_FOR_GITEA_WIKI` | Token Gitea, tiada yang lain | Menulis halaman wiki bagi repositori dalam organisasi yang memilih menyertainya | -- Token yang digunakan mesti mempunyai skop `write:repository`, dan penggunanya mesti mempunyai akses tulis kepada repositori ini. Gitea tidak mempunyai skop untuk wiki sahaja. -- `TOKEN_FOR_GITEA` didokumenkan di atas dengan `read:repository` sahaja. Menggunakannya semula untuk wiki bermakna meningkatkan skopnya, yang juga memberi akses tulis kepada penyegerakan metadata. `TOKEN_FOR_GITEA_WIKI` yang berasingan untuk pengguna khusus mengekalkan token penyegerakan sebagai baca sahaja. S05 memutuskan yang mana, dan S03 menyimpan secret. +- Simpan sebagai secret organisasi bagi setiap repositori yang menerbitkan. Tiada sandaran kepada `TOKEN_FOR_GITEA`: repositori yang telah memilih menyertainya dan tidak mempunyai secret itu gagal dengan ralat konfigurasi, dan repositori yang tidak memilih tidak memerlukannya. +- Token mesti mempunyai skop `write:repository`, dan penggunanya mesti mempunyai akses tulis kepada repositori. Gitea tidak mempunyai skop untuk wiki sahaja, jadi cipta token untuk pengguna khusus. S05 meluluskan skop dan S03 menyimpan secret. - Panggilan yang dibuat: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`, `GET`, `POST` dan `PATCH /repos/{owner}/{repo}/wiki/...` dan, bagi halaman yang tidak lagi wujud dalam `wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}`. - Wiki mesti diaktifkan dalam tetapan repositori. Aliran kerja enggan berjalan jika ia tidak diaktifkan. -- Wiki sentiasa sama dengan `wiki/`: halaman yang diedit atau ditambah dalam antara muka web Gitea ditimpa atau dibuang pada penerbitan seterusnya. +- Halaman yang ada dalam `wiki/` sentiasa ditimpa daripadanya, jadi perubahan yang dibuat dalam antara muka web Gitea hilang pada penerbitan seterusnya. Halaman yang hanya ada dalam wiki dibuang hanya apabila `wiki/.publish` mengandungi perkataan `prune`. ## Menukar token diff --git a/wiki/Home.da.md b/wiki/Home.da.md index f660eb4..4b87abe 100644 --- a/wiki/Home.da.md +++ b/wiki/Home.da.md @@ -1,4 +1,4 @@ - + > Dette er en oversættelse af [`Home`](Home). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres. @@ -23,7 +23,7 @@ Det indeholder i øjeblikket Gitea-workflowet [`sync-github-metadata.yml`](https - Repository-secrets: - `TOKEN_FOR_GITEA`: Gitea API-token (kun tokenet, ingen JSON) - `PAT_FOR_GITHUB`: et GitHub personal access token, der må redigere spejl-repositoryet (kun tokenet, ingen JSON) - - `TOKEN_FOR_GITEA_WIKI` (valgfri, kun i dette repository, til workflowet **Publish wiki**): Gitea-token, der kan skrive til repositoryets wiki; hvis den mangler, bruges `TOKEN_FOR_GITEA`, som så skal have skriveadgang + - `TOKEN_FOR_GITEA_WIKI` (kun for repositories, der publicerer en wiki, se [tilslutningsvejledningen](Onboarding.da)): et Gitea-token, der kan skrive til wikien, gemt som en secret i repositoryets organisation; der er ingen reserve til `TOKEN_FOR_GITEA` ## Opsætning diff --git a/wiki/Home.md b/wiki/Home.md index fcc1c61..f330ec4 100644 --- a/wiki/Home.md +++ b/wiki/Home.md @@ -23,7 +23,7 @@ It currently contains the Gitea workflow [`sync-github-metadata.yml`](https://gi - Repository secrets: - `TOKEN_FOR_GITEA`: Gitea API token (the token only, no JSON) - `PAT_FOR_GITHUB`: a GitHub personal access token allowed to edit the mirror repository (the token only, no JSON) - - `TOKEN_FOR_GITEA_WIKI` (optional, only in this repository, for the **Publish wiki** workflow): Gitea token that can write the repository wiki; when it is absent, `TOKEN_FOR_GITEA` is used and needs write access + - `TOKEN_FOR_GITEA_WIKI` (only for repositories that publish a wiki, see the [onboarding guide](Onboarding)): a Gitea token that can write the wiki, stored as a secret of the repository's organization; there is no fallback to `TOKEN_FOR_GITEA` ## Setup diff --git a/wiki/Home.ms.md b/wiki/Home.ms.md index 8c7c776..5e5d8ca 100644 --- a/wiki/Home.ms.md +++ b/wiki/Home.ms.md @@ -1,4 +1,4 @@ - + > Ini ialah terjemahan [`Home`](Home). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya. @@ -23,7 +23,7 @@ Buat masa ini ia mengandungi aliran kerja Gitea [`sync-github-metadata.yml`](htt - Rahsia (secret) repositori: - `TOKEN_FOR_GITEA`: token API Gitea (token sahaja, tanpa JSON) - `PAT_FOR_GITHUB`: personal access token GitHub yang dibenarkan mengubah suai repositori cermin (token sahaja, tanpa JSON) - - `TOKEN_FOR_GITEA_WIKI` (pilihan, hanya dalam repositori ini, untuk aliran kerja **Publish wiki**): token Gitea yang boleh menulis ke wiki repositori; jika tiada, `TOKEN_FOR_GITEA` digunakan dan mesti mempunyai akses tulis + - `TOKEN_FOR_GITEA_WIKI` (hanya untuk repositori yang menerbitkan wiki, lihat [panduan menyertakan repositori](Onboarding.ms)): token Gitea yang boleh menulis ke wiki, disimpan sebagai secret organisasi repositori; tiada sandaran kepada `TOKEN_FOR_GITEA` ## Persediaan diff --git a/wiki/Onboarding.da.md b/wiki/Onboarding.da.md index 4b8f579..6a8ecdc 100644 --- a/wiki/Onboarding.da.md +++ b/wiki/Onboarding.da.md @@ -1,4 +1,4 @@ - + > Dette er en oversættelse af [`Onboarding`](Onboarding). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres. @@ -30,6 +30,18 @@ Leveringen er automatisk, så et repository behøver ingen kopi af workflowet. S 6. **Kør det én gang manuelt:** Actions, **Sync GitHub mirror metadata**, Run workflow. Loggen skal slutte med `Synced description and topics to /.`, og GitHub-repositoryet skal vise samme beskrivelse og emner. 7. Hvis det fejler, brug [troubleshooting.md](Troubleshooting.da). +## Publicér en wiki (valgfrit) + +Workflowet **Publish wiki** kopierer Markdown-siderne i `wiki/` til repositoryets wiki, når en ændring af `wiki/` flettes til `main`. Det leveres som synkroniseringsworkflowet, men skriver kun, hvor et repository har meldt sig til. + +1. Aktivér wikien i repositoryets indstillinger. +2. Tilføj Markdown-sider til `wiki/`. Filnavnet er sidens navn: `Home.md` er forsiden. +3. Tilføj markøren `wiki/.publish`. Lad den være tom for kun at oprette og opdatere sider. Skriv det ene ord `prune` i den for også at slette wiki-sider, der ikke findes i `wiki/`, så wikien altid er lig med mappen. +4. Gem `TOKEN_FOR_GITEA_WIKI` som en secret i repositoryets organisation med det scope, der står i [credentials.md](Credentials.da). +5. Flet ændringen til `main`. Loggen skal slutte med `Published page(s) to the wiki of /`. + +Et repository uden `wiki/.publish` springes over med linjen `No wiki/.publish marker in /`: intet bliver skrevet, og der skal ingen secret til. + ## Runners | Punkt | Værdi | diff --git a/wiki/Onboarding.md b/wiki/Onboarding.md index 548a1aa..196ac22 100644 --- a/wiki/Onboarding.md +++ b/wiki/Onboarding.md @@ -49,6 +49,27 @@ Delivery is automatic, so a repository needs no copy of the workflow. Secrets ar and topics. 7. If it fails, use [troubleshooting.md](Troubleshooting). +## 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. + +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. +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. +4. Store `TOKEN_FOR_GITEA_WIKI` as a secret of the repository's organization, + using the scope in [credentials.md](Credentials). +5. Merge the change to `main`. The log must end with `Published page(s) to + the wiki of /`. + +A repository without `wiki/.publish` is skipped with the line `No +wiki/.publish marker in /`: nothing is written and no secret is +needed. + ## Runners | Item | Value | diff --git a/wiki/Onboarding.ms.md b/wiki/Onboarding.ms.md index 2ee766a..5eb83cb 100644 --- a/wiki/Onboarding.ms.md +++ b/wiki/Onboarding.ms.md @@ -1,4 +1,4 @@ - + > Ini ialah terjemahan [`Onboarding`](Onboarding). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya. @@ -30,6 +30,18 @@ Penghantaran adalah automatik, jadi repositori tidak memerlukan salinan aliran k 6. **Jalankan sekali secara manual:** Actions, **Sync GitHub mirror metadata**, Run workflow. Log mesti berakhir dengan `Synced description and topics to /.` dan repositori GitHub mesti menunjukkan penerangan dan topik yang sama. 7. Jika gagal, gunakan [troubleshooting.md](Troubleshooting.ms). +## Menerbitkan wiki (pilihan) + +Aliran kerja **Publish wiki** menyalin halaman Markdown dalam `wiki/` ke wiki repositori apabila perubahan pada `wiki/` digabungkan ke `main`. Ia dihantar seperti aliran kerja penyegerakan, tetapi hanya menulis di tempat repositori telah memilih untuk menyertainya. + +1. Aktifkan wiki dalam tetapan repositori. +2. Tambah halaman Markdown ke `wiki/`. Nama fail ialah nama halaman: `Home.md` ialah halaman utama. +3. Tambah penanda `wiki/.publish`. Biarkan kosong untuk mencipta dan mengemas kini halaman sahaja. Letakkan satu perkataan `prune` di dalamnya untuk turut memadam halaman wiki yang tiada dalam `wiki/`, supaya wiki sentiasa sama dengan folder itu. +4. Simpan `TOKEN_FOR_GITEA_WIKI` sebagai secret organisasi repositori, dengan skop yang tertera dalam [credentials.md](Credentials.ms). +5. Gabungkan perubahan ke `main`. Log mesti berakhir dengan `Published page(s) to the wiki of /`. + +Repositori tanpa `wiki/.publish` dilangkau dengan baris `No wiki/.publish marker in /`: tiada apa-apa ditulis dan tiada secret diperlukan. + ## Runners | Perkara | Nilai | diff --git a/wiki/Troubleshooting.da.md b/wiki/Troubleshooting.da.md index 60574da..2f47961 100644 --- a/wiki/Troubleshooting.da.md +++ b/wiki/Troubleshooting.da.md @@ -1,4 +1,4 @@ - + > Dette er en oversættelse af [`Troubleshooting`](Troubleshooting). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres. @@ -30,7 +30,8 @@ Kategorien fortæller, hvor du skal kigge. En fejl uden for scriptet (jobbet sta | `TOKEN_FOR_GITEA is missing or empty.` | configuration | Tilføj secreten | | `Could not determine the Gitea source repository.` | configuration | Kørslen har intet repositorynavn; meld det som en defekt | | `Expected at most one GitHub push mirror ... found N` | configuration | Behold ét GitHub push-spejl | -| `No token for the wiki: set TOKEN_FOR_GITEA_WIKI, or TOKEN_FOR_GITEA.` | configuration | Kun wiki-publicering: tilføj en af secrets (se [credentials.md](Credentials.da)) | +| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Kun wiki-publicering: repositoryet har meldt sig til med `wiki/.publish`, men dets organisation har ingen sådan secret; gem den (se [credentials.md](Credentials.da)) | +| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Kun wiki-publicering: lad markøren være tom, eller skriv kun ordet `prune` i den | | `... HTTP 403 ...` ved publicering af wikien | permissions | Kun wiki-publicering: tokenet skal have `write:repository` og skriveadgang til dette repository | | `The wiki is not enabled on ` | configuration | Kun wiki-publicering: aktivér wikien i repositoryets indstillinger | | `The wiki source directory ... has no Markdown pages` | configuration | Kun wiki-publicering: `wiki/` er tom eller mangler; intet blev ændret | @@ -50,6 +51,10 @@ Kategorien fortæller, hvor du skal kigge. En fejl uden for scriptet (jobbet sta `WARNING: Gitea returned an invalid push mirror list; GitHub metadata was not synced.` Kørslen lykkes, men intet blev synkroniseret. Kontroller, at Gitea-versionen understøtter push mirror-API'et, og kør igen. +`No wiki/.publish marker in /; wiki publishing is not enabled for this repository.` Kørslen af Publish wiki lykkes og skriver intet. Repositoryet har ikke meldt sig til; tilføj `wiki/.publish`, hvis det skal publicere. + +` page(s) are in the wiki but not in wiki/ and were kept; put the word 'prune' in wiki/.publish to delete them.` Kørslen lykkes. Sider, der kun findes i wikien, lades i fred, medmindre markøren indeholder `prune`. + ## Runner-problemer Se afsnittet [Runners](Onboarding.da#runners). Kort sagt: hvis kørslen bliver stående som `waiting`, har ingen online runner labelen; hvis jobbet fejler før scriptet, mangler runner-imaget et værktøj. diff --git a/wiki/Troubleshooting.md b/wiki/Troubleshooting.md index ffe9ffa..736fc3e 100644 --- a/wiki/Troubleshooting.md +++ b/wiki/Troubleshooting.md @@ -32,7 +32,8 @@ 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 | -| `No token for the wiki: set TOKEN_FOR_GITEA_WIKI, or TOKEN_FOR_GITEA.` | configuration | Wiki publishing only: add one of the secrets (see [credentials.md](Credentials)) | +| `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)) | +| `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 | | `... 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 ` | 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 | @@ -57,6 +58,14 @@ settings. 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 /; 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. + +` 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`. + ## Runner problems See the [Runners](Onboarding#runners) section. In short: if the run stays diff --git a/wiki/Troubleshooting.ms.md b/wiki/Troubleshooting.ms.md index 229f880..6153378 100644 --- a/wiki/Troubleshooting.ms.md +++ b/wiki/Troubleshooting.ms.md @@ -1,4 +1,4 @@ - + > Ini ialah terjemahan [`Troubleshooting`](Troubleshooting). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya. @@ -30,7 +30,8 @@ Kategori menunjukkan di mana perlu dilihat. Kegagalan di luar skrip (kerja tidak | `TOKEN_FOR_GITEA is missing or empty.` | configuration | Tambah secret | | `Could not determine the Gitea source repository.` | configuration | Larian tiada nama repositori; laporkan sebagai kecacatan | | `Expected at most one GitHub push mirror ... found N` | configuration | Kekalkan satu push mirror GitHub | -| `No token for the wiki: set TOKEN_FOR_GITEA_WIKI, or TOKEN_FOR_GITEA.` | configuration | Penerbitan wiki sahaja: tambah salah satu secret (lihat [credentials.md](Credentials.ms)) | +| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Penerbitan wiki sahaja: repositori telah memilih menyertainya dengan `wiki/.publish` tetapi organisasinya tiada secret itu; simpannya (lihat [credentials.md](Credentials.ms)) | +| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Penerbitan wiki sahaja: biarkan penanda kosong, atau letakkan hanya perkataan `prune` di dalamnya | | `... HTTP 403 ...` semasa menerbitkan wiki | permissions | Penerbitan wiki sahaja: token memerlukan `write:repository` dan akses tulis kepada repositori ini | | `The wiki is not enabled on ` | configuration | Penerbitan wiki sahaja: aktifkan wiki dalam tetapan repositori | | `The wiki source directory ... has no Markdown pages` | configuration | Penerbitan wiki sahaja: `wiki/` kosong atau tiada; tiada apa-apa diubah | @@ -50,6 +51,10 @@ Kategori menunjukkan di mana perlu dilihat. Kegagalan di luar skrip (kerja tidak `WARNING: Gitea returned an invalid push mirror list; GitHub metadata was not synced.` Larian berjaya tetapi tiada apa-apa disegerakkan. Semak bahawa versi Gitea menyokong API push mirror dan jalankan semula. +`No wiki/.publish marker in /; wiki publishing is not enabled for this repository.` Larian Publish wiki berjaya dan tidak menulis apa-apa. Repositori belum memilih menyertainya; tambah `wiki/.publish` jika ia sepatutnya menerbitkan. + +` page(s) are in the wiki but not in wiki/ and were kept; put the word 'prune' in wiki/.publish to delete them.` Larian berjaya. Halaman yang hanya ada dalam wiki dibiarkan melainkan penanda mengandungi `prune`. + ## Masalah runner Lihat bahagian [Runners](Onboarding.ms#runners). Ringkasnya: jika larian kekal `waiting`, tiada runner dalam talian yang mempunyai label itu; jika kerja gagal sebelum skrip, imej runner tiada satu alat.