sjat
db76be2a63
- ADR-011: ruled-out row was "digest-pinning stateful" (contradicted Decision 2); now "digest-only (no readable tag)" — tag@digest is adopted (O7) - ADR-003/010: act_runner names ubongo as the runner host, runner VM as a future option (O8) - ADR-008: WireGuard Molecule-exclusion row reframed to NetBird wt0 data plane (O9) - ADR-011: scheduled_jobs xref points to TODO 8.3, not ADR-010 (O10) - CAPABILITIES: add /verify-service Level 4 capability row (O11) - TODO 3.10: rewrite the garbled base-container question (O12) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
77 lines
2.8 KiB
Markdown
77 lines
2.8 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**
|
|
(item `boma-forgejo-api`), fetched via `rbw get boma-forgejo-api` (run `rbw sync`
|
|
first if it was just added), **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 `ubongo` (the control node — ADR-015), or a dedicated runner VM
|
|
later if CI load warrants a separate host. 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. |
|