vole

Clone

Read only, no credentials:

https://rodent.software/vole.git

Write over SSH with a registered key:

git clone ssh://git@rodent.software:2222/vole.git

A free and open-source forge that lives in your Git repo.

Docs: rewrite the README and organize the guides

520470e19cd906bd6fff987e2d132d793ce56486 · Keenan Nemetz · 16d ago · parent c5902451

Docs: rewrite the README and organize the guides

Replace the long README with a landing page, split feature details into focused guides, and remove the roadmap and spike notes. Update comments that referenced them.

docs/users-and-access.md +96

@@ -0,0 +1,96 @@
	1	# Users and access
	2
	3	Vole has no password database and no login screen. Your SSH key is your identity:
	4	the same key you use to push. That means one less account system to maintain, and
	5	one less password to protect.
	6
	7	## Accounts and keys
	8
	9	An account has a permanent id and a name you can change. Access rules and
	10	approvals are attached to the permanent id, so renaming an account does not break
	11	anything.
	12
	13	Names are never reused. When you retire an account, its keys stop working and its
	14	name stays reserved. An old reference can never silently point at a different
	15	person.
	16
	17	Account data lives in `data/users.db`. It also holds repository access rules and
	18	file locks. Nothing in the file is secret. Vole reloads it every few seconds, so
	19	key changes and retirements take effect without restarting the server.
	20
	21	```sh
	22	vole user create alice
	23	vole user add-key alice --key ~/.ssh/id_ed25519.pub
	24	vole user list
	25	vole user rm-key alice SHA256:...
	26	vole user rename alice a-alice
	27	vole user retire alice
	28	vole user backup backup/users.db
	29	```
	30
	31	To see which account the current remote's key belongs to:
	32
	33	```sh
	34	vole whoami
	35	vole whoami --id
	36	```
	37
	38	## Roles
	39
	40	Each repository has a default role for everyone and optional roles for specific
	41	accounts.
	42
	43	\| Role \| What it allows \|
	44	\|---\|---\|
	45	\| `none` \| No access \|
	46	\| `read` \| Clone, fetch, and browse the repository \|
	47	\| `write` \| Push normal branches and work with issues and change requests \|
	48	\| `admin` \| Manage access, push protected branches, override locks, and repair metadata \|
	49
	50	A new repository is private. Its default role is `none`, and its owner is an
	51	admin. Private repositories return `404` to anonymous visitors, so people cannot
	52	tell whether they exist.
	53
	54	To publish a repository, give the default role `read`:
	55
	56	```sh
	57	vole acl default demo read
	58	```
	59
	60	## Changing access
	61
	62	```sh
	63	vole acl show demo
	64	vole acl set demo alice write
	65	vole acl set demo bob read
	66	vole acl default demo read
	67	vole acl protect demo refs/heads/main
	68	vole acl approvals demo 2
	69	vole acl checks demo on
	70	vole acl runners demo ci-runner-1
	71	```
	72
	73	- `set` gives one account a role.
	74	- `default` changes the role for everyone else. `read` or higher makes the
	75	repository public.
	76	- `protect` replaces the list of protected branch patterns. Admins can still push
	77	to them directly.
	78	- `approvals` sets how many approvals a protected branch needs. `0` means
	79	admin-only.
	80	- `checks` requires CI checks to pass before a protected branch can be updated.
	81	- `runners` names the accounts whose CI results this repository trusts. Admins
	82	always count. See [CI](ci.md#who-can-run-jobs-and-report-results).
	83
	84	## When rules are checked
	85
	86	Every rule is checked before Vole accepts a push. If a push breaks a rule, none of
	87	its branches move.
	88
	89	That includes protected branches, approvals, required checks, file size limits,
	90	locks, issue formatting, and the CI runner allowlist. Privileged actions — such as
	91	an admin force-push, a lock override, a user change, or a merge through review —
	92	are written to `data/audit.log`.
	93
	94	For the reasoning behind this design, see
	95	[Architecture](architecture.md#trust-your-key-is-your-identity). For file locks, see
	96	[LFS § Locking](lfs.md#locking-files).