Record the S01 stand-in rule and the wiki publish token decision
ADR-0002: an artifact approved by S01 counts as approved for the other named reviewers, with the stand-in recorded. ADR-0003: the wiki is published with a separate TOKEN_FOR_GITEA_WIKI, dot-named titles work. Add review records RC-013 and RC-014 and update TM-001.
This commit is contained in:
@@ -0,0 +1,69 @@
|
||||
# ADR-0002: S01 approves as stand-in for other reviewers
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | ADR-0002 |
|
||||
| CrossReference | [SA-001], [RC-001] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
|
||||
|
||||
Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The project plan names reviewers by stakeholder ID: S01 (Product Owner) is
|
||||
the approving reviewer, S05 (DevOps owner and security authority) owns the
|
||||
milestones, and S03 operates runners and secrets. The Stakeholder Analysis
|
||||
([SA-001]) says credential, token and permission design cannot be accepted
|
||||
without S05, and the Business Case lists S05's review of every security-relevant
|
||||
change as the mitigation for a risk. In practice S01 has been approving
|
||||
documents and has stood in for S05 and S03 (the first time is recorded in
|
||||
[RC-001]), because there is currently one person doing all three roles. The
|
||||
framework also requires that a reviewer is not the author of an artifact.
|
||||
|
||||
Options:
|
||||
|
||||
1. **Require each named person to review.** The record is independent, but
|
||||
work waits for a person who is not available in the project's current
|
||||
setup, and the S05 actions in RC-001 and RC-011 stayed open.
|
||||
2. **S01 approves for everyone and the records say so.** Work continues, and
|
||||
each record names who really approved.
|
||||
3. **Drop the other reviewers from the documents.** Simple, but it hides who
|
||||
is accountable and removes the way back to independent review.
|
||||
|
||||
## Decision
|
||||
|
||||
An artifact approved by S01 counts as approved for the stakeholders named
|
||||
as its reviewers or action owners (S05, S03), and the record says that S01
|
||||
stood in. This applies to every artifact of this project, including the review
|
||||
records themselves, until a named stakeholder asks to review in their own
|
||||
right; that person's review then replaces the stand-in for later changes.
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive:**
|
||||
|
||||
- Work is not blocked by a reviewer who is not present, and the records stay honest about who approved.
|
||||
- The way back to independent review is kept: the stakeholder IDs stay in the documents.
|
||||
|
||||
**Negative:**
|
||||
|
||||
- No independent check: the author, the approving reviewer and the stand-in are the same person, so a security-relevant change (credentials, tokens, permissions, workflow code) has had no second reader.
|
||||
- It conflicts with the text of [SA-001] (S05 must accept credential, token and permission design) and with the Business Case mitigation "S05 reviews every change"; both still say so and need an amendment, or S05 needs to be told.
|
||||
- The framework rule that the reviewer must not be the author is not met; this is a project deviation to be taken upstream, not a framework change.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- [SA-001] — the statement that credential, token and permission design cannot be accepted without S05 no longer holds.
|
||||
- [RC-001] — its action item for an independent S05 review is closed by this decision; the other records that refer to it follow.
|
||||
|
||||
---
|
||||
|
||||
[SA-001]: ../stakeholder-analysis.md
|
||||
[RC-001]: ../sqa/reviews/rc-001-business-case.md
|
||||
@@ -0,0 +1,70 @@
|
||||
# ADR-0003: Wiki publish token and dot-named page titles
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | ADR-0003 |
|
||||
| CrossReference | [MIL-005], [ADR-0001], [RC-011] |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
|
||||
|
||||
Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The Publish wiki workflow (MIL-005 task 8) writes the Gitea wiki and so
|
||||
needs a token that can write to the repository. The existing `TOKEN_FOR_GITEA`
|
||||
only reads (`read:repository`) and is used by the metadata sync, so raising its
|
||||
scope would also give the sync write access. Gitea has no wiki-only scope.
|
||||
After the first publish two open points from [ADR-0001] and [RC-011] were
|
||||
answered: pages with a dot in the title are accepted, and the stored secret
|
||||
must hold the bare token string (a value of the form `NAME=token` is rejected
|
||||
with HTTP 401).
|
||||
|
||||
Options:
|
||||
|
||||
1. **Reuse `TOKEN_FOR_GITEA` and raise its scope.** One secret, but the
|
||||
metadata sync gets write access it does not need.
|
||||
2. **A separate `TOKEN_FOR_GITEA_WIKI` for a dedicated user.** One more
|
||||
secret to store and rotate, and the sync token stays read-only.
|
||||
3. **Push to the wiki repository by hand.** No secret, but unreviewed content
|
||||
and no record of who published.
|
||||
|
||||
## Decision
|
||||
|
||||
The wiki is published with a separate secret, `TOKEN_FOR_GITEA_WIKI`, holding
|
||||
a bare Gitea token with scope `write:repository` for a dedicated user that has
|
||||
write access to this repository only; the workflow falls back to
|
||||
`TOKEN_FOR_GITEA` only when it is absent. Dot-named titles (`Home.da`,
|
||||
`Home.ms`) are kept as ADR-0001 decided.
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive:**
|
||||
|
||||
- The metadata sync token stays read-only, so a leak of it cannot change the wiki or the code.
|
||||
- The first publish (run 65) created all 15 pages and a read-back matched `wiki/` byte for byte.
|
||||
- A rejected token is diagnosed from the log (length and shape, never the value).
|
||||
|
||||
**Negative:**
|
||||
|
||||
- One more secret to store and rotate, at organisation level for now; scoping it to this repository is a follow-up for the person who administers the secrets.
|
||||
- The fallback to `TOKEN_FOR_GITEA` can hide a missing wiki secret until a write is refused (HTTP 403).
|
||||
- The credentials guide and MIL-005 task 2 still say that S05 decides which token to use; the decision is recorded here.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- [MIL-005] — task 2 and task 8 (issues #33 and #42) are settled by this decision.
|
||||
- [ADR-0001] — its negative consequence about dot-named titles is resolved: they work.
|
||||
- [RC-011] — its action items for the secret scope (S05) and for storing the secret (S03) are done.
|
||||
|
||||
---
|
||||
|
||||
[MIL-005]: ../milestones/mil-005-wiki-and-translations.md
|
||||
[ADR-0001]: ./adr-0001-wiki-structure-and-languages.md
|
||||
[RC-011]: ../sqa/reviews/rc-011-mil-005-wiki-publishing.md
|
||||
Reference in New Issue
Block a user