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.

Rewrite the README around the new tagline

e73d453fe4edf2d95ec7e178dad0c232b5ece1c7 · Keenan Nemetz · 2d ago · parent 18c559ea

Rewrite the README around the new tagline

"A forge that lives in your Git repo" replaces "A small but mighty software
forge that lives in your Git repository" everywhere it is the brand line: the
README, the docs index, and the .deb/.rpm description. The built-in landing-page
tagline becomes the same sentence, so a new instance shows it without config.

The package description said CI records live in Git. They live in
data/runs.db, so it now says CI history stays on the instance, and it names
comments, which do live in the vole branch, and says reviews where it used to
say approvals.

The README is the front page and nothing else: the tagline, why the project is
worth using, and links. The quick start, the documentation table, and the
browser sign-in setup move out; the first two are already in the docs, which the
README now links. Development notes move to DEVELOPMENT.md. The private
repository 404 note is dropped because docs/accounts-and-access.md covers it,
and Contributing no longer tells coding agents to read AGENTS.md.

README.md +21−120

@@ -1,130 +1,31 @@
	1	1	# Vole
	2	2
	3		A small but mighty software forge that lives in your Git repository.
		3	A forge that lives in your Git repo.
	4	4
	5		Vole is for developers who value ownership, simplicity, and resilience over feature
	6		count. Code, issues, change requests, approvals, and releases live in Git. CI
	7		history lives in the instance's database. Runners run where you put them. There is
	8		no control plane in a data center you do not own.
		5	Vole keeps a project's work beside its code. Issues, comments, change requests,
		6	reviews, and releases are stored in Git, so a clone carries all of it. CI history
		7	stays on your own instance.
	9	8
	10	9	## Why Vole
	11	10
	12		- Your repository survives outages. Issues, reviews, approvals, and releases
	13		clone with the code, so the work that belongs to the repository is not trapped
	14		in a vendor's database. CI history stays on your instance and is backed up with
	15		it. When a hosting service goes down, your repository does not.
	16		- CI is not tied to a vendor. Add a workflow, start a runner anywhere it can run
	17		an OCI runtime (Docker, rootless Podman, or nerdctl), and Vole sends it work over
	18		SSH. Your build machines can be a server, a spare desktop, or a box in the closet.
	19		- It is easy to run. One binary, one config file, and no extra services to
	20		operate. Vole can obtain its own TLS certificates, so a public instance does
	21		not need a proxy in front of it. You do not need a cloud account to get started.
	22		- Browser sign-in without passwords. People who file issues can enroll a
	23		passkey from a one-time link; there is no password database to protect.
	24		- Admins can work from anywhere. Instance admins can create accounts,
	25		repositories, and access rules over the same SSH connection, from any machine.
	26		- It is small on purpose. Fewer moving parts, fewer things to break, and a
	27		codebase you can read. Vole focuses on the work most teams actually do.
	28		- It is open source. The whole thing is yours to read, run, and change, under
	29		the [Apache License 2.0](LICENSE).
		11	- An outage does not stop you. Nothing sits in a vendor's database, so a clone
		12	with the code is a copy of the work.
		13	- CI runs where you put it. Start a runner anywhere with Docker, Podman, or
		14	nerdctl and Vole sends it work over SSH. A spare desktop is a build machine.
		15	- One binary, one config file. No database server, no message queue, and no
		16	proxy: Vole obtains its own TLS certificates. No cloud account needed.
		17	- Sign in without passwords. People who file issues enroll a passkey from a
		18	one-time link, so there is no password database to protect.
		19	- Small on purpose. Fewer moving parts, and a codebase you can read end to
		20	end.
	30	21
	31		## What Vole is not
	32
	33		Vole is deliberately smaller than GitHub or GitLab. It does not try to be everything to
	34		every team. If you need a large feature matrix or enterprise controls, another
	35		forge is probably a better fit.
	36
	37		## Quick start
	38
	39		```sh
	40		go build -tags libsqlite3,sqlite_fts5 -o vole ./cmd/vole
	41
	42		./vole admin init --dir . # create config and data/users.db
	43		./vole admin account create you --key ~/.ssh/id_ed25519.pub
	44		./vole admin repo create demo --owner you
	45		./vole admin acl set-default-role demo read # publish: the repository is private until you do this
	46		./vole serve # SSH :2222, web :8080
	47		```
	48
	49		Vole links SQLite dynamically, so building needs a C compiler and the SQLite
	50		development headers (`libsqlite3-dev` on Debian and Ubuntu, `sqlite-devel` on
	51		Fedora and RHEL), and the binary needs `libsqlite3.so.0` where it runs.
	52
	53		Write with your key. Read without one:
	54
	55		```sh
	56		git clone ssh://git@127.0.0.1:2222/demo.git # read/write, key required
	57		git clone http://127.0.0.1:8080/git/demo.git # read only, no credentials
	58		```
	59
	60		To let people file issues and approve change requests in a browser, set `public_url` to
	61		the instance's `https://` address. Add `https_addr` if you want Vole to obtain the
	62		certificate itself instead of running a proxy, then create an account and its
	63		enrollment link:
	64
	65		```sh
	66		vole admin account create reporter
	67		```
	68
	69		To let people create their own accounts, set `open_registration = true` alongside
	70		an HTTPS `public_url`. New accounts start with no repository-specific access; set
	71		`open_registration_role = "contribute"` to give them an instance-wide role that
	72		applies to every public repository.
	73
	74		New repositories are private. If someone opens a private repository on the web,
	75		they get a `404` — the same answer as a repository that does not exist — so Vole
	76		never confirms that it is there.
		22	Vole is deliberately smaller than GitHub or GitLab. If you need a wide feature
		23	matrix or enterprise controls, another forge will serve you better.
	77	24
	78	25	## Learn more
	79	26
	80		\| If you want to… \| Start here \|
	81		\|---\|---\|
	82		\| Set up your first repository \| [Getting started](docs/getting-started.md) \|
	83		\| Put an instance on a server \| [Deploying](docs/deploy/README.md) \|
	84		\| Change bind addresses, limits, or proxy settings \| [Configuration](docs/configuration.md) \|
	85		\| Add accounts and choose what they can do \| [Accounts and access](docs/accounts-and-access.md) \|
	86		\| Keep issues with the code \| [Issues](docs/issues.md) \|
	87		\| Review and merge change requests \| [Change requests](docs/change-requests.md) \|
	88		\| Write CI workflows \| [Workflows](docs/workflows.md) \|
	89		\| Look up workflow and image fields \| [Workflow reference](docs/reference/workflow-reference.md) · [Image reference](docs/reference/image-reference.md) \|
	90		\| Run builds on your own machines \| [Runners](docs/runner.md) \|
	91		\| Store large files or lock editable files \| [LFS](docs/lfs.md) \|
	92		\| Publish a release \| [Releases](docs/releases.md) \|
	93		\| Host a website from a repository \| [Sites](docs/sites.md) \|
	94		\| Back up or recover an instance \| [Operations](docs/operations.md) \|
	95		\| Install a `.deb` or `.rpm` \| [Packages](docs/packaging.md) \|
	96
	97		Reference: [CLI commands](docs/cli.md) · [Architecture](docs/architecture.md)
	98
	99		Full index: [docs/README.md](docs/README.md).
	100
	101		## Development
	102
	103		```sh
	104		go test -tags sqlite_fts5 ./...
	105		vole workflow run verify # everything CI runs, before you push
	106		```
	107
	108		The checks live in [`.vole/workflows/verify.yaml`](.vole/workflows/verify.yaml),
	109		so the workflow and `vole workflow run verify` cannot drift apart: a local run executes the
	110		steps in the same image, so it needs a container runtime (Docker, Podman, or
	111		nerdctl) rather than the tools installed on your `PATH`. The workflow needs network
	112		for module downloads, which is why the runner that takes it is started with
	113		`--container-network bridge`; the local run defaults to the same network.
	114
	115		Vole is also usable as a Go library. See
	116		[Architecture § Using Vole as a library](docs/architecture.md#using-vole-as-a-library).
	117
	118		## Contributing and coding agents
	119
	120		This repository uses Vole for its own work. Start with
	121		[CONTRIBUTING.md](CONTRIBUTING.md) for the forge workflow, issue and
	122		change-request rules, and the checks to run before pushing. Coding agents should
	123		also read [AGENTS.md](AGENTS.md), the short operational layer over the same
	124		workflow.
	125
	126		## License
	127
	128		Apache License 2.0. See [LICENSE](LICENSE) for the terms and [NOTICE](NOTICE) for
	129		bundled third-party components. Contributions are accepted under the same terms;
	130		there is no contributor license agreement.
		27	- [Documentation](docs/README.md): build it, deploy it, and look up a command.
		28	- [Contributing](CONTRIBUTING.md): the issue and change-request workflow.
		29	- [Development](DEVELOPMENT.md): tests, the checks CI runs, and using Vole as a
		30	Go library.
		31	- [License](LICENSE): Apache 2.0. Third-party notices are in [NOTICE](NOTICE).