diff --git a/docs/decisions/010-forgejo-ci.md b/docs/decisions/010-forgejo-ci.md index 836fa74..72cbff5 100644 --- a/docs/decisions/010-forgejo-ci.md +++ b/docs/decisions/010-forgejo-ci.md @@ -1,5 +1,9 @@ # ADR-010 — Forgejo integration and CI +## Status + +Accepted (2026-05-30) + ## Context boma's git host, container registry, and (planned) CI all run on a self-hosted @@ -20,7 +24,7 @@ held to the same standard as the rest of the repo's secrets. --- -## Decisions +## Decision ### 1. API tokens are managed secrets, least-privilege @@ -75,3 +79,21 @@ later if CI load warrants a separate host. Actions is not yet enabled — see ST | 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. | + +--- + +## Consequences + +- The planned CI pipeline (see "CI pipeline (planned)") is trunk-based per ADR-003 / + ADR-008 — `push to main → lint + Molecule → deploy staging → [manual gate] → deploy + production` — running `act_runner` on `ubongo` (or a dedicated runner VM later if CI + load warrants); Actions is not yet enabled, so this remains future work tracked in + STATUS.md. +- Terraform state is not held in Forgejo: its `/raw/` API is read-only and cannot be + written, so local state is used instead (ADR-006) (see "What was ruled out"). +- Automation tokens are scoped to `read:repository` + `read`/`write:package` rather + than admin, accepting the limits that least-privilege imposes on what automation can + do (see "What was ruled out"). +- Instance/repo configuration must be codified or documented rather than changed + ad-hoc, to avoid the undocumented drift `/review-repo` exists to catch (see "What was + ruled out"). diff --git a/docs/decisions/011-update-management.md b/docs/decisions/011-update-management.md index c96bbe6..95552e0 100644 --- a/docs/decisions/011-update-management.md +++ b/docs/decisions/011-update-management.md @@ -1,5 +1,9 @@ # ADR-011 — Update and upgrade management +## Status + +Accepted (2026-06-04) + **Status: Proposed — draft for discussion (not yet accepted).** ## Context @@ -10,7 +14,7 @@ drift over time and must be kept current without breaking the homelab: the **hos --- -## Decisions +## Decision ### 1. Every service is classified stateful or stateless @@ -132,3 +136,19 @@ alert-driven. | 8-weekly as the only stateful path | Too slow for urgent CVEs — hence the DIUN security fast-path. | --- + +## Consequences + +- A single uniform update policy is rejected: the stateful/stateless split is + load-bearing, so stateless services roll on rolling tags while stateful services are + pinned `tag@digest`, human-gated, and backup-first (see "What was ruled out"). +- The weekly run never touches stateful services and the whole fleet is never updated + at once, accepting the added orchestration of host ordering and an 8-weekly + + fast-path cadence in exchange for bounded blast radius (see "What was ruled out"). +- No update automation ships until the health-check verification gate is in order; the + pipeline is deliberately sequenced behind that harness (see Decision 6). +- Several points remain open for discussion (see "Open questions"): where the Proxmox + snapshot is driven from across the TF/Ansible boundary; the exact cadences; where the + health-check harness lives and the minimum bar that counts as "in order"; whether + classification is a per-role `__stateful` flag or a group_vars list; whether the + weekly run hits staging first; and the notification + "skip/pause" control channel. diff --git a/docs/decisions/013-heritage-v4.md b/docs/decisions/013-heritage-v4.md index f90aa92..082ac38 100644 --- a/docs/decisions/013-heritage-v4.md +++ b/docs/decisions/013-heritage-v4.md @@ -1,5 +1,9 @@ # ADR-013 — Heritage: learning from AnsibleBaobabV4 without inheriting it +## Status + +Accepted (2026-06-04) + ## Context boma is the methodology successor to AnsibleBaobabV4 (and V3 before it) — not a new @@ -10,7 +14,9 @@ structure and assumptions creep back in under the guise of "inspiration." This A sets the policy for drawing on V4 without inheriting it. (Resolves the questions previously parked in TODO 3.3 and 10.1.) -## Principle — translate, don't transplant +## Decision + +### Principle — translate, don't transplant V4 is **evidence, never authority.** It can show what was needed or what went wrong; it can never be the reason boma does something a certain way. @@ -21,7 +27,7 @@ it can never be the reason boma does something a certain way. - **Acceptance test** for anything V4-derived: *can it be justified purely from boma's principles, with zero reference to V4?* If not, it does not land. -## What V4 is — and is not — a source of +### What V4 is — and is not — a source of | Legitimate source of | Never a source of | |---|---| @@ -33,7 +39,7 @@ it can never be the reason boma does something a certain way. Only concrete, verifiable, low-level knowledge crosses over — precisely because it is safe to re-derive, whereas structure and requirements drag assumptions along. -## Provenance — transient only +### Provenance — transient only When a boma decision was prompted by a V4 lesson, or a config adapted from V4, the lineage is recorded only in **transient** places: the commit message, the working @@ -42,7 +48,7 @@ extraction warrants one. **Durable artifacts (ADRs, role READMEs, `SECURITY.md`) stand on boma's own terms with no V4 reference.** Honest about lineage in history; clean in the living repo. -## AI consultation guardrails +### AI consultation guardrails The AI is the main consumer of V4 — it is on disk and readable. When consulting it: