sjat
37cece9dbd
ADR-010: API tokens as least-privilege managed secrets, declarative-first (no click-ops), automation boundary, planned trunk-based CI. CLAUDE.md/AGENTS.md: check 'rbw unlocked' before vault-dependent tasks (incl. commits) rather than failing partway. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
76 lines
2.7 KiB
Markdown
76 lines
2.7 KiB
Markdown
# ADR-010 — Forgejo integration and CI
|
|
|
|
## Context
|
|
|
|
boma's git host, container registry, and (planned) CI all run on a self-hosted
|
|
Forgejo instance at `forgejo.nyumbani.baobab.band` (SSH on 7577, HTTPS on 443). Both
|
|
humans and AI/automation interact with it. This ADR sets the principles so the
|
|
instance does not become undocumented click-ops drift, and so its credentials are
|
|
held to the same standard as the rest of the repo's secrets.
|
|
|
|
---
|
|
|
|
## What Forgejo provides here
|
|
|
|
- **Git hosting** — `origin` (push/pull over SSH; key-based, not token).
|
|
- **Container registry** — hosts the Molecule test image
|
|
(`forgejo.nyumbani.baobab.band/sjat/molecule-debian13`); see ADR-008.
|
|
- **Actions CI** — planned, not yet enabled (`has_actions: false`); trunk-based
|
|
pipeline per ADR-003 / ADR-008.
|
|
|
|
---
|
|
|
|
## Decisions
|
|
|
|
### 1. API tokens are managed secrets, least-privilege
|
|
|
|
A Forgejo API token (PAT) is a secret and follows ADR-002: stored in **Vaultwarden**,
|
|
fetched via `rbw`/env, **never** written to a file or pasted into chat. Tokens are
|
|
**least-privilege** — scoped to their purpose, never admin.
|
|
|
|
Note what does *not* need a token: git push/pull (SSH key), and Terraform state
|
|
(local — ADR-006). A token for CI / registry use needs only:
|
|
|
|
- `read:repository`
|
|
- `read:package`, `write:package` (pull/push the Molecule image)
|
|
|
|
### 2. Declarative-first, not click-ops
|
|
|
|
Forgejo configuration lives in the repo where possible:
|
|
|
|
- Actions workflows in `.forgejo/workflows/` (version-controlled).
|
|
- Repo/instance settings are codified or documented; changing them ad-hoc via the
|
|
API or UI is a **documented exception**, recorded when done — not the norm.
|
|
|
|
The point: the Forgejo instance must not become the kind of undocumented drift that
|
|
`/review-repo` exists to catch.
|
|
|
|
### 3. Automation boundary
|
|
|
|
Automation / AI **may**, via the API or CLI: read repo and CI state, manage the
|
|
container registry, run and inspect CI. It must **not**, without explicit human
|
|
direction: change instance/admin settings, delete repos or packages, or rotate
|
|
credentials.
|
|
|
|
---
|
|
|
|
## CI pipeline (planned)
|
|
|
|
Trunk-based, matching ADR-003 / ADR-008:
|
|
|
|
```
|
|
push to main → lint + Molecule → deploy staging → [manual gate] → deploy production
|
|
```
|
|
|
|
Runner: `act_runner` on the control node or a dedicated runner VM. Actions is not
|
|
yet enabled — see STATUS.md.
|
|
|
|
---
|
|
|
|
## What was ruled out
|
|
|
|
| Option | Reason |
|
|
|---|---|
|
|
| Terraform Forgejo HTTP state backend | Forgejo's `/raw/` API is read-only; state can't be written there. Local state instead (ADR-006). |
|
|
| Admin-scoped automation tokens | Unnecessary privilege; scope to `read:repository` + `read`/`write:package`. |
|
|
| Ad-hoc UI/API configuration as the norm | Becomes undocumented drift; codify or document instead. |
|