# Forgejo Admin API Token (PAT)

Date: 2026-07-12  
Catalog: `forgejo-admin-api-token` (status `draft`, `resolvable: false` until verified)  
Owner: `railiance-platform` (CCR-2026-0006)

Forgejo site-admin personal access token for operator and automation tooling.
Sibling to `forgejo-mailer` (SMTP via ESO); phase 1 is workstation + activity-core
worker fetch only — no cluster ExternalSecret delivery.

---

## OpenBao pointers

| Field | Value |
| --- | --- |
| Mount | `platform` |
| Path | `platform/workloads/forgejo/forgejo-admin` |
| Secret field | `API_TOKEN` (PAT value) |
| Metadata fields | `API_USER`, `API_BASE_URL`, `TOKEN_SCOPES`, `GENERATED_AT` (optional, non-secret) |
| Policy | `workload-kv-read-forgejo-admin` |
| OIDC role | `forgejo-admin-workload-kv-read` (`groups=net-kingdom-admins`) |

**PAT scopes (minimum for current consumers):** `read:package`, `write:package`,
`read:repository`, `write:repository`, plus admin scopes as needed for
`forgejo-operator-bootstrap` (mirror the current admin PAT).

**Forgejo account:** `tegwick` (site admin, `coulomb` Owners).

---

## Worker checklist

1. **Login** (caller identity — ops-warden adds no credential):

   ```bash
   bao login -method=oidc -path=netkingdom role=forgejo-admin-workload-kv-read
   ```

2. **Export for a Forgejo API run** (value streams to your shell — never paste into chat):

   ```bash
   export FORGEJO_ADMIN_TOKEN=$(
     bao kv get -field=API_TOKEN platform/workloads/forgejo/forgejo-admin
   )
   ```

3. **Or proxy via warden access** (after catalog promotion):

   ```bash
   warden access forgejo-admin-api-token --no-policy --fetch --field API_TOKEN
   ```

4. **Run consumers**:

   ```bash
   # Package prune (railiance-platform)
   make forgejo-package-prune-dry-run
   make forgejo-package-prune

   # Operator bootstrap / npm smoke / reuse webhook (railiance-apps)
   make forgejo-operator-bootstrap
   make forgejo-npm-smoke
   make reuse-forgejo-webhook
   ```

5. **Retire workstation file drop** once downstream `load_token()` paths read
   OpenBao when env is unset:

   - `/tmp/forgejo-tegwick-api-token` — legacy; do not use as steady state
   - `FORGEJO_ADMIN_TOKEN` env — acceptable for one-off sessions after fetch

---

## Operator provisioning (attended)

After CCR approval and policy apply:

1. Forgejo UI: `tegwick` → Settings → Applications → Generate New Token
2. Store in OpenBao (do not echo the value):

   ```bash
   bao kv put platform/workloads/forgejo/forgejo-admin \
     API_TOKEN=@/path/to/pat-file \
     API_USER=tegwick \
     API_BASE_URL=https://forgejo.coulomb.social \
     TOKEN_SCOPES='read:package,write:package,read:repository,write:repository' \
     GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
   ```

3. Verify field presence without printing values:

   ```bash
   bao kv metadata get platform/workloads/forgejo/forgejo-admin
   ```

---

## Consumers (downstream wiring — after lane verified)

| Consumer | Repo |
| --- | --- |
| `tools/cmd/forgejo-package-prune` | `railiance-platform` |
| `weekly-forgejo-package-prune` activity | `activity-core` |
| `forgejo-operator-bootstrap`, `forgejo-npm-smoke`, `reuse-forgejo-webhook` | `railiance-apps` |

Docs: `railiance-platform/docs/forgejo-package-prune.md`,
`railiance-apps/docs/forgejo-on-railiance01.md`.

---

## See also

- `railiance-platform/credential-change-requests/CCR-2026-0006-forgejo-admin-api-token-lane.yaml`
- `railiance-platform/openbao/policies/workload-kv-read-forgejo-admin.hcl`
- `wiki/playbooks/railiance-backup-offsite-lane.md` (OIDC workstation read pattern)
- `forgejo-mailer` lane — SMTP only; unchanged