| name | forgejo-admin |
| description | Administer the canonical Forgejo server - converge branch protection and repo PR/merge settings across owned repos, plus docker/git credential auth through the attended admin-token helper. Use when protecting a branch after creating a repo, auditing drift, converging merge policy, or fixing Forgejo docker/git credential failures. Aliases - forgejo branch protection, forgejo repo settings, forgejo docker auth, forgejo git credentials, forgejo-creds. |
Forgejo admin
Status: 🛠 Runbook | Last updated: 2026-07-13
Administering the canonical Forgejo server: branch protection, repo PR/merge
settings, and the credential helpers that let docker/git reach private Forgejo.
Three surfaces, one server. Read the relevant references/ doc before acting.
Branch protection - when and how
Converge the rule whenever the repo set changes, most importantly right after creating
a new repo (the newcomer starts unprotected). This is a converge, not a one-time
migration -> safe and expected to re-run any time. There is no commit-time guard, so
the script itself is the rollout.
ward exec forgejo-branch-protection applies by default. Add dry_run=1 to
preview, then use repo=<name> (one repo) or limit=<n> to narrow before
committing to the whole fleet. The run is idempotent and API-only (no checkout):
already-protected repos report ok and are left untouched, per-repo failures
are non-fatal and land in the closing summary.
What the rule enforces, which owners are in scope, the admin-token helper, and the
verify curl are all in references/forgejo-branch-protection.md. Contract and CLI flags
(--dry-run / --repo / --limit / --owner) live in
scripts/forgejo-branch-protection.py. The verb applies by default.
PR-gated repos can carry required status contexts through the same converge. The
current tracked set is in the reference doc, and cli-guard is documented there as
waiting on its PR workflow prerequisite.
Repo settings - when and how
Branch protection applies by default. Repo settings do as well. Run repo
settings when fleet policy changes or after creating matching repo. ward exec forgejo-repo-settings applies by default across owned repos. dry_run=1 is
the preview path. Details are in
references/forgejo-repo-settings.md.
Decision cues:
- Made a new repo -> re-run the converge to protect it.
- Suspect drift or want an audit on branch protection ->
dry_run=1.
- Repo settings -> default apply,
dry_run=1 previews.
- Scoped ->
repo= / owner= / limit=.
Docker / git auth - what it covers
Separate concern: making a fresh host authenticate to private Forgejo without a local
checkout. The forgejo-creds Ansible role installs two helpers into ~/.local/bin/ -
git-credential-forgejo-ssm.sh (git) and docker-credential-forgejo-ssm (docker) -
and wires git config plus ~/.docker/config.json. Both fetch the Forgejo admin
token through the attended helper on demand and never write it to disk.
Reach for this when docker build from a forgejo.coilysiren.me Git context or a
registry pull fails auth on a fresh host. The fix is running / re-running
forgejo-creds, not the branch-protection script - the two share only the SSM token
path. Full mechanism, config, and security notes are in
references/forgejo-docker-git-auth.md.
Pointers
references/forgejo-branch-protection.md - the protection rule, scope, verify.references/forgejo-repo-settings.md - merge policy, scope, verify.references/forgejo-docker-git-auth.md - credential helpers and forgejo-creds.scripts/forgejo-branch-protection.py - the converge script and flags.scripts/forgejo-repo-settings.py - the repo settings converge script and flags.ward exec forgejo-branch-protection - apply-by-default entry point.ward exec forgejo-repo-settings - apply-by-default entry point.
