sjat/boma
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
boma/docs/decisions/010-forgejo-ci.md
sjat 37cece9dbd Add ADR-010 (Forgejo integration) and rbw-unlocked pre-flight convention 
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>
2026-05-30 21:34:07 +02:00

2.7 KiB
Raw Blame History

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.