No way to bootstrap governance: add git-collab-server setup #87

New issue

Closed

opened 2026-08-13 09:55:37 +00:00 by a73x · 0 comments

a73x commented

2026-08-13 09:55:37 +00:00

(Migrated from git.a73x.sh)

Governance shipped in b6dcbb7b and the exposure model in 1beeb03e, and nothing can create a settings.git. Proven by the live deployment: it runs the code and hosts five repositories, and /data/repos/ has no settings repo, so governance is present and entirely inert.

Follow gitolite: gitolite setup takes an admin pubkey and creates gitolite-admin. We stole the rest of that design; this is the missing piece.

git-collab-server setup --config <path> --admin-key <file|->

It must be an explicit command, never automatic on startup. The exposure model makes unlisted-and-unreadable the default where governance is in force, and creating settings.git is exactly what puts it in force. A server that seeded one on boot would, at the moment it upgraded, make every repository invisible until someone wrote rules — rule 3's protection undone by the feature meant to make governance usable.

The seed should reproduce the current effective policy, so enabling governance is behaviourally a no-op. That is what makes it safe to run on a live server, and it is the difference between a bootstrap and a switch nobody dares flip:

keydir/ seeded from the admin key given, and named for the identity it belongs to.
conf/access.conf granting that principal RW+ on settings, so the operator can push changes immediately — otherwise setup locks them out of the thing it just created.
A block per existing repository reproducing what server.toml grants it today, including R = @anonymous and option listed = yes where the repo is currently public. Discovery already enumerates them; read each one's current policy and write the equivalent rule.
Written and committed as one commit containing both files, never a roster then rules — the push-time guard added in 1beeb03e r2 refuses that pair, and the seed must not create by hand the state that guard exists to prevent.

Requirements worth pinning:

Refuse to run if settings.git already exists, rather than overwriting an operator's rules.
--dry-run printing the access.conf it would write. An operator should read the policy before it governs their server.
Report the identity it derived from the key, since the keydir basename is the principal and getting it wrong locks you out.
Do not touch authorized_keys; leave the pre-governance path working until the operator is satisfied.

Found while asking where settings.git was on the live server, and finding the answer is nowhere and there is no way to make one.

Migrated from git-collab issue 3733cccdb2d779b3bc36aa7b4da9a426f71bfe9d.

Original author: a73x dev@a73x.sh.

Close reason: merged in patch 0065cd95

Governance shipped in b6dcbb7b and the exposure model in 1beeb03e, and nothing can create a `settings.git`. Proven by the live deployment: it runs the code and hosts five repositories, and `/data/repos/` has no settings repo, so governance is present and entirely inert. Follow gitolite: `gitolite setup` takes an admin pubkey and creates `gitolite-admin`. We stole the rest of that design; this is the missing piece. ``` git-collab-server setup --config <path> --admin-key <file|-> ``` **It must be an explicit command, never automatic on startup.** The exposure model makes unlisted-and-unreadable the default *where governance is in force*, and creating `settings.git` is exactly what puts it in force. A server that seeded one on boot would, at the moment it upgraded, make every repository invisible until someone wrote rules — rule 3's protection undone by the feature meant to make governance usable. **The seed should reproduce the current effective policy, so enabling governance is behaviourally a no-op.** That is what makes it safe to run on a live server, and it is the difference between a bootstrap and a switch nobody dares flip: - `keydir/` seeded from the admin key given, and named for the identity it belongs to. - `conf/access.conf` granting that principal `RW+` on `settings`, so the operator can push changes immediately — otherwise setup locks them out of the thing it just created. - A block per existing repository reproducing what `server.toml` grants it today, including `R = @anonymous` and `option listed = yes` where the repo is currently public. Discovery already enumerates them; read each one's current policy and write the equivalent rule. - Written and committed as **one commit containing both files**, never a roster then rules — the push-time guard added in 1beeb03e r2 refuses that pair, and the seed must not create by hand the state that guard exists to prevent. Requirements worth pinning: - Refuse to run if `settings.git` already exists, rather than overwriting an operator's rules. - `--dry-run` printing the `access.conf` it would write. An operator should read the policy before it governs their server. - Report the identity it derived from the key, since the keydir basename *is* the principal and getting it wrong locks you out. - Do not touch `authorized_keys`; leave the pre-governance path working until the operator is satisfied. Found while asking where `settings.git` was on the live server, and finding the answer is nowhere and there is no way to make one. --- Migrated from git-collab issue `3733cccdb2d779b3bc36aa7b4da9a426f71bfe9d`. Original author: a73x <dev@a73x.sh>. Close reason: merged in patch 0065cd95