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.

Code

392 commit(s) on main

Compare History

Merge change request 01M70WES5ZZDJ6RP226WB11BBZ: Let people rename and remove their own passkeys keenan · 58m ago 4b8c9e1d

source preview history blame raw 4.9 KiB

1	# Releases
2
3	A release should travel with the code. In Vole, it does: a release is a Git tag
4	with a message. The message is the release notes, and the tagged code is the
5	source. Both travel with every clone, so there is no separate release database to
6	keep in sync.
7
8	## Create a release
9
10	```sh
11	vole release create v1.0.0 -F notes.md
12	git push --follow-tags
13	```
14
15	Plain Git works the same way:
16
17	```sh
18	git tag -a v1.0.0 -F notes.md
19	git push --follow-tags
20	```
21
22	Use an annotated tag (`git tag -a`). It has a message and a tagger. A lightweight
23	tag appears in the release list for completeness, but it has no notes and cannot
24	carry release files. `vole release create` refuses to overwrite an existing tag
25	and tells you to choose a new name.
26
27	## Create a release in the browser
28
29	A repository maintainer can create the same annotated tag from **Releases → New
30	release**: choose a tag name, a target branch or commit, and write the notes. The
31	notes become the tag message and the tagger is the account that submitted the
32	form. Edit notes changes the message of an annotated tag while the release has
33	no files attached; once an artifact is published the release is immutable, and
34	the web refuses the edit. Lightweight tags are never editable.
35
36	## Download source archives
37
38	The `/<repo>/releases` page lists every tag. A release page shows the notes, the
39	commits since the previous release, and two generated downloads:
40
41	```sh
42	curl -O http://host/demo/releases/v1.0.0/archive.tar
43	curl -OJ http://host/demo/releases/v1.0.0/archive.tar.gz
44	```
45
46	Vole builds the archives from the tagged tree when someone requests them, so they
47	cannot go stale. The `ETag` is the tag's id, so repeat downloads get a `304`, and
48	the same tag produces the same bytes on every instance.
49
50	If a repository tracks files with Git LFS, the release page shows a warning.
51	`git archive` copies pointer files, not the files themselves.
52
53	## Attach release files
54
55	Binaries attach over SSH into the shared storage, and Vole records a pointer for
56	them:
57
58	```sh
59	vole release attach v1.0.0 dist/vole-linux-amd64 dist/vole-darwin-arm64
60	curl -O http://host/demo/releases/v1.0.0/artifacts/vole-linux-amd64
61	sha256sum vole-linux-amd64
62	```
63
64	Attach files after pushing the tag, not before. The pointer is what publishes the
65	file, and Vole refuses a pointer whose file was never uploaded. That way a
66	download link never points at nothing.
67
68	If you attach the same file twice, Vole stores one copy and the second upload
69	transfers nothing. Downloads support `ETag`, `304`, `Content-Disposition:
70	attachment`, and Range requests, so large files can resume. Files from a private
71	repository return `404`.
72
73	## Releases do not change
74
75	Once a release has files attached, Vole refuses to move or delete that tag, remove
76	a file, or point a file name at different bytes. A saved download keeps meaning
77	what it meant.
78
79	You can add another file; that does not invalidate anything. An admin can repair a
80	mistyped release, and the override is recorded in `data/audit.log`.
81
82	Release file pointers live on the `vole` branch, so `vole admin gc --dry-run` treats a
83	published release file as something to keep.
84
85	## Build a release in CI
86
87	A workflow can build and publish a release instead of attaching files by hand:
88
89	```yaml
90	artifacts:
91	- path: dist/*
92	release: true
93	```
94
95	The run records the same pointers that `vole release attach` writes, so the
96	release page, download behavior, and immutability rules stay the same. See
97	[Workflows § Build a release](workflows.md#build-a-release).
98
99	## A bill of materials for each release
100
101	A release built by the workflow carries an SBOM: `vole-<version>.sbom.cdx.json`,
102	in CycloneDX JSON, listed on the release page beside the packages and covered by
103	`SHA256SUMS`.
104
105	It names every Go module the application links, with the version and hash that
106	`go.sum` pins, the Go toolchain, and each module's licence as detected evidence
107	rather than an asserted conclusion. That is what makes it useful for the question
108	it exists to answer: an advisory names a module version, and the SBOM says whether
109	the binary you downloaded contains it.
110
111	Two limits, stated so nobody reads more into it than is there:
112
113	- One file covers both architectures. The module graph is the same for
114	`amd64` and `arm64`; only the compiled files differ. Check it with
115	`GOOS=linux GOARCH=arm64 go list -deps ./cmd/vole`.
116	- The system SQLite library is not a Go module. The SBOM names
117	`github.com/mattn/go-sqlite3`, the binding the build links, not the
118	`libsqlite3-0` version underneath it. That one comes from the package you
119	installed: `dpkg -s vole` or `rpm -q --requires vole`.
120
121	To regenerate it for a tag you already have:
122
123	```sh
124	go run github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@v1.9.0 \
125	app -json -noserial -std -licenses -main cmd/vole -output SBOM.cdx.json .
126	```
127
128	The only field the tool takes from the clock is `metadata.timestamp`; the workflow
129	replaces it with the tag's commit time, so building one tag twice produces the
130	same file.
131