boma/docs/decisions/010-forgejo-ci.md

# 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
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.

---

## Decision

### 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. |

---

## 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").