forgejo-admin

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.