vole

Clone

Read only, no credentials:

https://rodent.software/git/vole.git

Write over SSH with a registered key:

git clone ssh://git@0.0.0.0:2222/vole.git

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

Add remote administration and local workflow runs

3abbe749096f4d7ff76f4d468e4427829b8a6f95 · Keenan Nemetz · 16d ago · parent 520470e1

Add remote administration and local workflow runs

Make `vole admin` the single namespace for user, repository, and access
management, runnable locally or over SSH by instance admins. Instance-admin
grants live in users.db, and the audit log names the actor separately from the
account being changed.

Add `vole workflow run` to execute workflow jobs in the working tree without a
server or runner. Positional arguments select workflows, --job selects jobs, and
the command reuses the push-time validator.

Update the README and guides for the new command shapes.

docs/operations.md +13−11

@@ -9,12 +9,12 @@ These are the tasks that keep an instance healthy.
	9	9	Back up three things:
	10	10
	11	11	```sh
	12		vole user backup backup/users.db # accounts, keys, access rules, locks
		12	vole admin user backup backup/users.db # accounts, keys, rules, admins, locks
	13	13	cp data/ssh_host_ed25519_key backup/ # the only secret on the machine
	14	14	cp data/audit.log backup/ 2>/dev/null # history of admin actions
	15	15	```
	16	16
	17		`vole user backup` takes a consistent copy, even while Vole is running. Copying
		17	`vole admin user backup` takes a consistent copy, even while Vole is running. Copying
	18	18	`users.db` by hand can miss recent changes that have not been written to the main
	19	19	database file yet.
	20	20
@@ -30,29 +30,29 @@ with them because they are stored in Git.
	30	30
	31	31	1. Restore `data/users.db`, `data/ssh_host_ed25519_key`, and `data/audit.log`.
	32	32	2. Restore the repositories under `data/repos/`.
	33		3. Run `vole index rebuild`.
		33	3. Run `vole admin index rebuild`.
	34	34	4. Start `vole serve`.
	35	35
	36	36	Large files, CI logs, and build artifacts live in `data/lfs/`. Back that directory
	37		up too if you need those files. `vole gc` treats files reachable from a
		37	up too if you need those files. `vole admin gc` treats files reachable from a
	38	38	repository, an archived CI log, or a published artifact as things to keep.
	39	39
	40	40	## Clean up stored files
	41	41
	42	42	```sh
	43		vole gc --dry-run # show what would be removed
	44		vole gc # remove unused files
	45		vole gc --grace 24h # keep unused files for a day
		43	vole admin gc --dry-run # show what would be removed
		44	vole admin gc # remove unused files
		45	vole admin gc --grace 24h # keep unused files for a day
	46	46	```
	47	47
	48		`vole gc` cleans the shared storage used by LFS, CI logs, and build artifacts. It
		48	`vole admin gc` cleans the shared storage used by LFS, CI logs, and build artifacts. It
	49	49	also repairs each repository's links into that storage, so it helps when files
	50	50	are missing or links are broken.
	51	51
	52	52	The default grace period is one hour. A recent upload that has not been pushed yet
	53	53	will not be removed.
	54	54
	55		You can run `vole gc` while people are pushing. There is no need to schedule it;
		55	You can run `vole admin gc` while people are pushing. There is no need to schedule it;
	56	56	storage only grows when someone pushes files.
	57	57
	58	58	## Rebuild indexes
@@ -60,12 +60,12 @@ storage only grows when someone pushes files.
	60	60	`data/index.db` is generated by Vole and can be deleted safely:
	61	61
	62	62	```sh
	63		vole index rebuild
		63	vole admin index rebuild
	64	64	```
	65	65
	66	66	`data/runs.db` holds the CI queue and run index. Deleting it loses attempts that
	67	67	were in progress. Vole queues current branch and tag tips again from Git, and
	68		`vole index rebuild` restores finished history from the run records on each
		68	`vole admin index rebuild` restores finished history from the run records on each
	69	69	repository's `vole` branch.
	70	70
	71	71	## Security notes
@@ -77,6 +77,8 @@ repository's `vole` branch.
	77	77	and the audit log.
	78	78	- The web interface is read-only. There is no password store, login, or session
	79	79	token.
		80	- Remote administration uses the same SSH listener and key. Only active instance
		81	admins can run it, and every admin command is audited.
	80	82	- Private repositories return `404` on the web and over HTTP, so visitors cannot
	81	83	confirm that they exist.
	82	84	- Vole does not handle TLS. Put it behind a proxy that terminates TLS and keeps