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

Decide the opt-in rule and secret handling of the shared wiki publisher (ADR-0004)

Browse Source 
A repository opts in with wiki/.publish; the word prune in it is the only
thing that lets the workflow delete pages. The shared workflow uses the
organisation's TOKEN_FOR_GITEA_WIKI only. Review and accept it (RC-018),
update TM-001 and link the MIL-006 milestone in PP-001.
This commit is contained in:
Tirsvad
2026-10-10 11:34:13 +08:00
parent 0230ed8c08
commit b22a2cd592
5 changed files with 179 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/adr/adr-0004-shared-wiki-publishing-opt-in.md
+116
View File
@@ -0,0 +1,116 @@
# ADR-0004: Opt-in rule and secret handling of the shared wiki publisher
## Metadata
| Key | Value |
| --- | --- |
| ID | ADR-0004 |
| CrossReference | [MIL-006], [ADR-0003], [ADR-0002] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | pending |
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Reviewed (RC-018): the `prune` variant added to the evaluated options | pending |
Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
---
## Context
MIL-006 turns the Publish wiki workflow into a scoped workflow, which Gitea
runs in every repository of every organisation on the instance (verified,
issue #9). The publisher writes to a repository's wiki and removes pages that
are not in `wiki/`. Without a gate, any of the 26 repositories of
`Tirsvad-Udemy-100-days-of-code`, or any other repository, that happens to
have a `wiki/` folder would have its wiki overwritten or emptied by a
workflow it never asked for. The secret is also per organisation, so the
shared workflow must say what happens where it is missing, and
[ADR-0003] let this repository fall back to `TOKEN_FOR_GITEA`.
Options for how a repository opts in:
1. **A marker file `wiki/.publish`** on the default branch. Visible in the
repository, reviewed in a pull request, and nothing to configure in an
organisation. It comes in two forms:
- **(a) the marker alone** makes the wiki equal `wiki/`, so pages that are
not in the folder are deleted, as in ADR-0003;
- **(b) the marker plus the word `prune`** in it: without the word the
workflow only creates and updates pages, and deleting is a second,
explicit choice.
2. **A repository variable** (for example `PUBLISH_WIKI=true`). Not part of
the repository content, so it is not reviewed or versioned, and it has to
be set in the web interface once per repository.
3. **An allow list** in this repository. One place to read, but every
repository in every organisation has to ask this repository for a change.
4. **Publish whenever `wiki/` exists.** No setup, which is the risk the gate
is meant to remove.
Option 1(b) is chosen for the reason in the first paragraph: a repository
that adds `wiki/` to a wiki it wrote by hand should not lose that wiki by
opting in.
Options for the secret:
1. **`TOKEN_FOR_GITEA_WIKI` of the organisation only.** The sync token stays
read-only everywhere.
2. **Fall back to `TOKEN_FOR_GITEA`** as in ADR-0003. A missing wiki secret is
hidden until a write is refused (HTTP 403).
## Decision
A repository opts in by committing `wiki/.publish` on its default branch; the
file may contain the single word `prune`, which is the only thing that lets the
workflow delete wiki pages that are not in `wiki/`, and without the marker the
workflow ends successfully without any request. The shared workflow uses the
organisation's `TOKEN_FOR_GITEA_WIKI` only, and fails with a configuration
error when a repository has opted in and the secret is missing.
The rules that follow from it:
- Without `prune` the workflow only creates and updates pages.
- An empty `wiki/` (no Markdown page) never deletes anything, with or without
`prune`.
- A repository that has not opted in is skipped with one log line, so its
runs stay green.
- This repository commits `wiki/.publish` containing `prune`, because its wiki
must equal `wiki/` (ADR-0001, ADR-0003).
- The fallback to `TOKEN_FOR_GITEA` of ADR-0003 is removed from the shared
workflow; the sync token is read-only everywhere.
## Consequences
**Positive:**
- A repository that did not opt in is never written to, and the marker is a
reviewed change in the repository that wants it.
- Deleting pages is a second, explicit choice, so adopting the workflow in a
repository with hand-written wiki pages loses nothing.
- A missing wiki secret is reported where it happens, in the repository that
opted in, and the sync token never gets write access.
**Negative:**
- Each organisation that wants this needs its own `TOKEN_FOR_GITEA_WIKI`; it
cannot borrow the sync token.
- A repository that opts in without `prune` keeps pages that were removed from
`wiki/`, so its wiki can drift from the folder until someone adds `prune`.
- Anyone with write access to a repository can opt it in and, with `prune`,
make the workflow delete its wiki pages; that is the intended scope of write
access, but it is not a separate approval.
- The change supersedes the fallback part of [ADR-0003], so the credentials
guide and the wiki pages that mention it need an update (MIL-006 task 5).
## Affected Artifacts
- [MIL-006] — tasks 2, 3 and 4 (issues #57 to #59) implement and pilot this
decision.
- [ADR-0003] — its fallback to `TOKEN_FOR_GITEA` no longer applies to the
shared workflow.
- [ADR-0002] — the stand-in rule applies to the review of this ADR.
---
[MIL-006]: ../milestones/mil-006-shared-wiki-publishing.md
[ADR-0003]: ./adr-0003-wiki-publish-token.md
[ADR-0002]: ./adr-0002-s01-approves-as-stand-in.md
docs/artifact-registry.md
+2 -2
View File
@@ -11,9 +11,9 @@ each document lives in *this* project and the next version to use.
| SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 |
| PP | Project Plan | docs/project-plan.md | 002 |
| MIL | Milestone / Gateway | docs/milestones/*.md | 007 |
| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 018 |
| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 019 |
| TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0004 |
| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0005 |
## Languages
docs/project-plan.md
+2 -1
View File
@@ -35,7 +35,7 @@ workflows. The Business Case sets no deadline, so the dates are proposals.
| Shared quality checks | [MIL-003] | 2026-11-02 to 2026-11-14 | 2026-11-14 | S05 | None yet | Reusable quality-check workflow | [Milestone MIL-003] |
| Versioned release and publishing | [MIL-004] | 2026-11-16 to 2026-11-28 | 2026-11-28 | S05 | None yet | Release process and reusable release workflow | [Milestone MIL-004] |
| Wiki and translations | [MIL-005] | 2026-11-30 to 2026-12-12 | 2026-12-12 | S05 | None yet | Wiki pages in English, Danish and Bahasa Malaysia, kept current by every pull request | [Milestone MIL-005] |
| Shared wiki publishing | [MIL-006] | 2026-12-14 to 2026-12-26 | 2026-12-26 | S05 | None yet | Scoped publish-wiki workflow with opt-in, piloted in one other repository | Not created yet |
| Shared wiki publishing | [MIL-006] | 2026-12-14 to 2026-12-26 | 2026-12-26 | S05 | None yet | Scoped publish-wiki workflow with opt-in, piloted in one other repository | [Milestone MIL-006] |
```plantuml
@startgantt
@@ -255,5 +255,6 @@ no tests, no release process.
[Milestone MIL-003]: https://git.tirsystem.com/TirSystem/github-action/milestone/20
[Milestone MIL-004]: https://git.tirsystem.com/TirSystem/github-action/milestone/21
[Milestone MIL-005]: https://git.tirsystem.com/TirSystem/github-action/milestone/93
[Milestone MIL-006]: https://git.tirsystem.com/TirSystem/github-action/milestone/94
[b282e10]: https://git.tirsystem.com/TirSystem/github-action/commit/b282e107416a890d6df27e6bdf23ab8a65e17123
[6b8e36d]: https://git.tirsystem.com/TirSystem/github-action/commit/6b8e36d67ac9af165b180bc0045289e41cfd1fc3
docs/sqa/reviews/rc-018-adr-0004.md
+51
View File
@@ -0,0 +1,51 @@
# Review Record: ADR-0004 Opt-in rule and secret handling of the shared wiki publisher
## Metadata
| Key | Value |
| --- | --- |
| ID | RC-018 |
| CrossReference | [ADR-0004], [QC-ADR-001] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
---
## Artifact Under Review
- Instance reviewed: [ADR-0004]
- Checklist used: [QC-ADR-001]
## Checklist Results
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | The ID (`ADR-NNNN`, 4-digit) matches the filename number and is unique and sequential | Pass | ADR-0004 in `adr-0004-shared-wiki-publishing-opt-in.md`; follows ADR-0003. |
| 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated | Pass | States the scoped delivery, the deletion risk, the per-organisation secret and the fallback. |
| 3 | At least two options were considered, or the absence of alternatives is justified | Pass | Four options for opting in (one with two forms) and two for the secret. |
| 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options | Pass | Finding fixed during this review: the `prune` form was not among the evaluated options. It is now option 1(b), with the reason. The decision is two sentences. |
| 5 | Consequences list both Positive and Negative outcomes | Pass | Three positive, four negative. |
| 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them | Pass | Security is named: no write without opt-in, no write access for the sync token, write access of anyone with repository write rights. |
| 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | MIL-006, ADR-0003 and ADR-0002 are linked and cited. |
| 8 | Status changes are recorded as new Version History rows with a Change summary and Commit link; retained rows are never rewritten | Pass | The earlier row is kept and only its status changed. |
| 9 | A superseded or deprecated ADR names its successor, and the successor links back | N-A | ADR-0003 is superseded only in part and stays in force for this repository's local workflow until MIL-006 task 2 lands; see the action item. |
| 10 | Written in business or technical language of the domain, with no unexplained abbreviations | Pass | IT Professional English; `prune` and the marker are explained where they are introduced. |
| 11 | Status is one of `Proposed`, `Accepted`, `Rejected`, `Deprecated` or `Superseded by ADR-NNNN`, and every Version History row uses only these | Pass | Deprecated and Accepted only. |
## Overall Verdict
Go - all applicable criteria pass; the one finding (criterion 4) was fixed during the review. S01 gave the Go in chat on 2026-10-10, standing in for the other reviewers as ADR-0002 records; there is no independent reader.
## Action Items
| Action | Owner | Due |
| --- | --- | --- |
| When MIL-006 task 2 (#57) merges, mark ADR-0003 as superseded by ADR-0004 for the shared workflow (new version row and review record) | S01 | 2026-12-26 |
| Choose the pilot repository (MIL-006 task 4, already an action item in RC-016) | S01 | 2026-12-14 |
---
[ADR-0004]: ../../adr/adr-0004-shared-wiki-publishing-opt-in.md
[QC-ADR-001]: ../../../framework/qc/qc-adr.md
docs/sqa/traceability-matrix.md
+8 -4
View File
@@ -4,13 +4,13 @@
| Key | Value |
| --- | --- |
| ID | TM-001 |
| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011], [RC-012], [RC-013], [RC-014], [RC-015], [RC-016], [RC-017], [ADR-0001], [ADR-0002], [ADR-0003] |
| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011], [RC-012], [RC-013], [RC-014], [RC-015], [RC-016], [RC-017], [RC-018], [ADR-0001], [ADR-0002], [ADR-0003], [ADR-0004] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added MIL-006 and RC-016 | [676a262] |
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added RC-017 for PP-001 | [676a262] |
| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added RC-017 for PP-001 | [676a262] |
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added ADR-0004 and RC-018 | pending |
---
@@ -45,7 +45,8 @@ updated whenever an artifact instance is created or reviewed.
| [RC-010] | RC | [MIL-005] | - | - |
| [ADR-0001] | ADR | [BC-001], [MIL-005] | [ADR-0003] | [RC-012] |
| [ADR-0002] | ADR | [SA-001], [RC-001] | - | [RC-013] |
| [ADR-0003] | ADR | [MIL-005], [ADR-0001], [RC-011] | - | [RC-014] |
| [ADR-0003] | ADR | [MIL-005], [ADR-0001], [RC-011] | [ADR-0004] | [RC-014] |
| [ADR-0004] | ADR | [MIL-006], [ADR-0003], [ADR-0002] | - | [RC-018] |
| [RC-011] | RC | [MIL-005] | - | - |
| [RC-012] | RC | [ADR-0001] | - | - |
| [RC-013] | RC | [ADR-0002] | - | - |
@@ -53,6 +54,7 @@ updated whenever an artifact instance is created or reviewed.
| [RC-015] | RC | [PP-001] | - | - |
| [RC-016] | RC | [MIL-006] | - | - |
| [RC-017] | RC | [PP-001] | - | - |
| [RC-018] | RC | [ADR-0004] | - | - |
## Coverage Notes
@@ -87,9 +89,11 @@ updated whenever an artifact instance is created or reviewed.
[ADR-0001]: ../adr/adr-0001-wiki-structure-and-languages.md
[ADR-0002]: ../adr/adr-0002-s01-approves-as-stand-in.md
[ADR-0003]: ../adr/adr-0003-wiki-publish-token.md
[ADR-0004]: ../adr/adr-0004-shared-wiki-publishing-opt-in.md
[RC-013]: ./reviews/rc-013-adr-0002.md
[RC-014]: ./reviews/rc-014-adr-0003.md
[RC-015]: ./reviews/rc-015-project-plan-pat.md
[RC-016]: ./reviews/rc-016-mil-006.md
[RC-017]: ./reviews/rc-017-project-plan-mil-006.md
[RC-018]: ./reviews/rc-018-adr-0004.md
[676a262]: https://git.tirsystem.com/TirSystem/github-action/commit/676a26240563338307c0454c3bf15b960bdb58ca