Merge pull request 'Document how a repository opts in to wiki publishing' (#63) from mil-006-guides-and-wiki into main
Reviewed-on: #63
This commit was merged in pull request #63.
This commit is contained in:
@@ -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) |
|
||||
|
||||
|
||||
+14
-12
@@ -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
|
||||
|
||||
|
||||
@@ -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 <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.
|
||||
|
||||
## Runners
|
||||
|
||||
| Item | Value |
|
||||
|
||||
@@ -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 <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 |
|
||||
@@ -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 <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.
|
||||
|
||||
`<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`.
|
||||
|
||||
## Runner problems
|
||||
|
||||
See the [Runners](onboarding.md#runners) section. In short: if the run stays
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Capabilities.md, source sha256 5856fdc70a30 -->
|
||||
<!-- translation of Capabilities.md, source sha256 737481cd7e09 -->
|
||||
|
||||
> 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) |
|
||||
|
||||
|
||||
@@ -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) |
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Capabilities.md, source sha256 5856fdc70a30 -->
|
||||
<!-- translation of Capabilities.md, source sha256 737481cd7e09 -->
|
||||
|
||||
> 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) |
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Credentials.md, source sha256 b810a21a07d5 -->
|
||||
<!-- translation of Credentials.md, source sha256 2660f2095b78 -->
|
||||
|
||||
> 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
|
||||
|
||||
|
||||
+14
-12
@@ -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
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Credentials.md, source sha256 b810a21a07d5 -->
|
||||
<!-- translation of Credentials.md, source sha256 2660f2095b78 -->
|
||||
|
||||
> 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
|
||||
|
||||
|
||||
+2
-2
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Home.md, source sha256 59273bf92278 -->
|
||||
<!-- translation of Home.md, source sha256 758940401ac1 -->
|
||||
|
||||
> 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
|
||||
|
||||
+1
-1
@@ -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
|
||||
|
||||
+2
-2
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Home.md, source sha256 59273bf92278 -->
|
||||
<!-- translation of Home.md, source sha256 758940401ac1 -->
|
||||
|
||||
> 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
|
||||
|
||||
+13
-1
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Onboarding.md, source sha256 17cf1b4c28c6 -->
|
||||
<!-- translation of Onboarding.md, source sha256 1d431898754e -->
|
||||
|
||||
> 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 <owner>/<repo>.`, 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 <n> page(s) to the wiki of <owner>/<repo>`.
|
||||
|
||||
Et repository uden `wiki/.publish` springes over med linjen `No wiki/.publish marker in <owner>/<repo>`: intet bliver skrevet, og der skal ingen secret til.
|
||||
|
||||
## Runners
|
||||
|
||||
| Punkt | Værdi |
|
||||
|
||||
@@ -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 <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.
|
||||
|
||||
## Runners
|
||||
|
||||
| Item | Value |
|
||||
|
||||
+13
-1
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Onboarding.md, source sha256 17cf1b4c28c6 -->
|
||||
<!-- translation of Onboarding.md, source sha256 1d431898754e -->
|
||||
|
||||
> 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 <owner>/<repo>.` 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 <n> page(s) to the wiki of <owner>/<repo>`.
|
||||
|
||||
Repositori tanpa `wiki/.publish` dilangkau dengan baris `No wiki/.publish marker in <owner>/<repo>`: tiada apa-apa ditulis dan tiada secret diperlukan.
|
||||
|
||||
## Runners
|
||||
|
||||
| Perkara | Nilai |
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Troubleshooting.md, source sha256 12672b3dde45 -->
|
||||
<!-- translation of Troubleshooting.md, source sha256 e8a34cbe7e93 -->
|
||||
|
||||
> 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 <repo>` | 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 <owner>/<repo>; 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.
|
||||
|
||||
`<n> 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.
|
||||
|
||||
+10
-1
@@ -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 <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 |
|
||||
@@ -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 <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.
|
||||
|
||||
`<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`.
|
||||
|
||||
## Runner problems
|
||||
|
||||
See the [Runners](Onboarding#runners) section. In short: if the run stays
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- translation of Troubleshooting.md, source sha256 12672b3dde45 -->
|
||||
<!-- translation of Troubleshooting.md, source sha256 e8a34cbe7e93 -->
|
||||
|
||||
> 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 <repo>` | 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 <owner>/<repo>; 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.
|
||||
|
||||
`<n> 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.
|
||||
|
||||
Reference in New Issue
Block a user