README
¶
letsgo
A release tool for Go. Only Go.
Status: early. letsgo releases itself, and reproducibility is proven across Linux, macOS and Windows on every push.
It builds your Go project, refuses to ship it if it's wrong, publishes it reproducibly, and lets anyone prove afterwards that the binaries match the source.
GoReleaser is a distribution tool. letsgo is an integrity tool. GoReleaser's job is getting your software to many places — Homebrew, Docker, deb, rpm, snap, AUR, Discord. It's very good at that. letsgo's job is proving a release is what it claims to be and never leaving it half-finished. If you need deb packages, snap or a dozen package managers, use GoReleaser for that repo.
Install
go install github.com/danielriddell21/letsgo/cmd/letsgo@latest
Or with the installer letsgo generated for its own release, which carries each archive's SHA-256 and fails rather than installing a substituted one:
curl -fsSL https://github.com/danielriddell21/letsgo/releases/latest/download/install.sh | sh
Or from the tap. letsgo writes the formula from the manifest it just published, so what brew installs is the archive the release attests to:
brew install danielriddell21/tap/letsgo
Usage
letsgo plan [--explain] [--json] [--publish] [--diff [--exit-code]] [--format md] [-out file] resolve and check a release without performing one
letsgo build [--snapshot] [-o dir] build every artifact into dist/ without publishing
letsgo release [--draft] [-o dir] build and publish, resumably
letsgo apply [file] [-auto-approve] publish a release as a saved plan agreed it; with no file, plan it, show it and ask
letsgo plan -yank <tag> [-out file] show what retracting a release would change
letsgo release --snapshot rehearse a release without publishing
letsgo verify [tag] [--json] [--words] rebuild a published release and compare it
letsgo doctor [--json] diagnose tools and repository state, read-only
letsgo audit [<tag>] re-check published releases against today's vulnerability database
letsgo diff <from> [to] [--format text|md|json] compare two releases: size, dependencies, API
letsgo promote <rc-tag> rebuild a prerelease as a stable release
letsgo yank <tag> [--reason "..."] retract a release, including the go.mod directive
letsgo tag [--major|--minor|--patch|--pre|--json] work out the next version and tag it
letsgo update [--check] update letsgo itself, verified against its manifest
letsgo plugin install [<name>] install a plugin, verified against its manifest (or every pin, with none)
letsgo plugin list [--json] the plugins this repository pins, and what is installed
letsgo plugin prune remove store entries no pin in this repository references
letsgo features [--json] the feature catalogue: what can be disabled or required
letsgo fmt [file|-] format letsgo.mod; - reads stdin, writes to stdout
letsgo lsp [--restricted] serve letsgo.mod over stdio JSON-RPC, for an editor
letsgo version print the version (also --version)
There is usually no config file — project name, module path, main packages, repo
owner and version are all derived from go.mod, git, and your directory
layout. letsgo plan resolves and checks all of it in about two seconds without
building anything, so a misconfigured release fails before the cross-compile
rather than after it.
cd ~/code/foo
git tag v1.3.0
letsgo plan # no side effects; --explain shows where each value came from
letsgo release # idempotent, so a failed run resumes rather than restarts
letsgo verify v1.3.0 # rebuild it and check it against what was published
Configuration
letsgo.mod is only needed to depart from what letsgo derives — optional
behaviours switched off with disable, made mandatory with require, plugins
pinned by digest, a Homebrew tap or container image turned on. Machine
settings that must not change what a release is — the Go and git to use, the
build cache, an opt-in update-check notice — go in a separate global
config.mod instead. See Configuration, Features and
Global config in the wiki.
In GitHub Actions
letsgo-action installs letsgo and runs it on a runner:
- uses: actions/setup-go@v7
with:
go-version-file: go.mod
- uses: danielriddell21/letsgo-action@v1
Go is a prerequisite rather than something the action installs: the Go version changes the bytes you ship, so choosing it belongs to the workflow that knows which one the project releases with. See GitHub Action for inputs, outputs, permissions and approval-gated releases.
Agreeing a release before making it
letsgo plan -out release.plan # build, read the forge, show and save what would change
letsgo apply release.plan # rebuild, refuse unless it matches the plan, then publish
The plan holds digests, not bytes. apply rebuilds and compares the manifest
before any write, so a changed toolchain or dependency between the two steps is
caught before anything is published. See Plan and apply for the plan
format, yank plans and an approval-gated release in CI.
After a release
The release body ends with a collapsed "what shipped" section comparing the
manifest against the previous release, letsgo audit re-checks a shipped
release against today's vulnerability database, and letsgo promote turns a
prerelease into the stable release it was rehearsing. See What shipped,
Audit and Prereleases.
Self-update
Any binary released with letsgo gets verified self-update for the cost of an import:
update, err := selfupdate.Check(ctx, selfupdate.Options{
Repo: "you/tool",
Current: version,
})
if err != nil || update == nil {
return err // a nil update means the running binary is current
}
return update.Apply(ctx)
Nothing is written until Apply, so a program can offer the update rather than
take it. letsgo update is the same package, pointed at letsgo — see
Self-update.
Documentation
Full documentation lives in the letsgo wiki: every command, monorepo releases, global config, editor support, publishing to Homebrew and container registries, plugins, the GitHub Action, migrating from GoReleaser, and the design rationale behind all of it.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
letsgo
command
Command letsgo builds and publishes Go releases.
|
Command letsgo builds and publishes Go releases. |
|
internal
|
|
|
archive
Package archive writes byte-for-byte reproducible release archives.
|
Package archive writes byte-for-byte reproducible release archives. |
|
audit
Package audit re-checks a shipped release's source against today's vulnerability database and records what it finds.
|
Package audit re-checks a shipped release's source against today's vulnerability database and records what it finds. |
|
brew
Package brew generates and publishes Homebrew formulas.
|
Package brew generates and publishes Homebrew formulas. |
|
build
Package build compiles and packages release artifacts.
|
Package build compiles and packages release artifacts. |
|
bump
Package bump works out which version a release should carry.
|
Package bump works out which version a release should carry. |
|
bytesize
Package bytesize parses and renders sizes in bytes.
|
Package bytesize parses and renders sizes in bytes. |
|
changelog
Package changelog turns a range of commits into release notes.
|
Package changelog turns a range of commits into release notes. |
|
config
Package config reads letsgo.mod, a configuration file written in the same line-and-block directive syntax as go.mod and go.work.
|
Package config reads letsgo.mod, a configuration file written in the same line-and-block directive syntax as go.mod and go.work. |
|
diff
Package diff compares two releases.
|
Package diff compares two releases. |
|
discover
Package discover derives everything letsgo needs from what is already in the repository: go.mod, the git remote, the directory layout, and the source itself.
|
Package discover derives everything letsgo needs from what is already in the repository: go.mod, the git remote, the directory layout, and the source itself. |
|
doctor
Package doctor diagnoses the tools and repository state a release needs, read-only and offline: see docs/hld/doctor.md.
|
Package doctor diagnoses the tools and repository state a release needs, read-only and offline: see docs/hld/doctor.md. |
|
feature
Package feature holds the catalogue of letsgo's optional behaviours: what each one is called, whether a repository may turn it off or make it strict, and what it defaults to.
|
Package feature holds the catalogue of letsgo's optional behaviours: what each one is called, whether a repository may turn it off or make it strict, and what it defaults to. |
|
forgetest
Package forgetest serves a letsgo-published release the way a forge does.
|
Package forgetest serves a letsgo-published release the way a forge does. |
|
gate
Package gate runs the correctness checks that decide whether a release is fit to publish.
|
Package gate runs the correctness checks that decide whether a release is fit to publish. |
|
gobuild
Package gobuild invokes the Go toolchain with the flags and environment a reproducible release requires.
|
Package gobuild invokes the Go toolchain with the flags and environment a reproducible release requires. |
|
install
Package install generates a self-verifying installer for a release.
|
Package install generates a self-verifying installer for a release. |
|
lsp
Package lsp implements letsgo lsp: a language server over stdio for letsgo.mod, the global config.mod and .letsgo/*.mod.
|
Package lsp implements letsgo lsp: a language server over stdio for letsgo.mod, the global config.mod and .letsgo/*.mod. |
|
manifest
Package manifest is letsgo's own view of a release manifest.
|
Package manifest is letsgo's own view of a release manifest. |
|
oci
Package oci builds container images without a daemon or a build system.
|
Package oci builds container images without a daemon or a build system. |
|
pgpwords
Package pgpwords encodes bytes as the PGP word list (Juola & Zimmermann, 1995), for reading a digest aloud.
|
Package pgpwords encodes bytes as the PGP word list (Juola & Zimmermann, 1995), for reading a digest aloud. |
|
plan
Package plan resolves a release without performing one.
|
Package plan resolves a release without performing one. |
|
plugin
Package plugin runs the external programs a repository may put in the middle of a release.
|
Package plugin runs the external programs a repository may put in the middle of a release. |
|
pluginstore
Package pluginstore is the content-addressed store plugin binaries are installed into.
|
Package pluginstore is the content-addressed store plugin binaries are installed into. |
|
promote
Package promote rebuilds a prerelease as a stable release.
|
Package promote rebuilds a prerelease as a stable release. |
|
publish
Package publish uploads a built release, idempotently.
|
Package publish uploads a built release, idempotently. |
|
publish/github
Package github publishes releases to GitHub.
|
Package github publishes releases to GitHub. |
|
randomart
Package randomart draws a digest as a drunken-bishop picture, the same fingerprint art OpenSSH prints for `ssh-keygen -lv`.
|
Package randomart draws a digest as a drunken-bishop picture, the same fingerprint art OpenSSH prints for `ssh-keygen -lv`. |
|
receipt
Package receipt renders a verification as a till receipt.
|
Package receipt renders a verification as a till receipt. |
|
receipt/code128
Package code128 encodes text as a Code 128 barcode in character set B.
|
Package code128 encodes text as a Code 128 barcode in character set B. |
|
release
Package release turns a plan into a complete set of publishable files.
|
Package release turns a plan into a complete set of publishable files. |
|
releasetest
Package releasetest builds a minimal, real release for tests that need release.Build's actual output — a source tree, a git tag, and the resulting manifest and archives — rather than a hand-rolled stand-in.
|
Package releasetest builds a minimal, real release for tests that need release.Build's actual output — a source tree, a git tag, and the resulting manifest and archives — rather than a hand-rolled stand-in. |
|
repro
Package repro drives the release pipeline for reproducibility testing.
|
Package repro drives the release pipeline for reproducibility testing. |
|
repro/cmd/reprodigest
command
Command reprodigest builds the reproducibility fixture and prints the resulting digests as JSON.
|
Command reprodigest builds the reproducibility fixture and prints the resulting digests as JSON. |
|
safeexec
Package safeexec constrains where helper programs are found and what they can find in turn.
|
Package safeexec constrains where helper programs are found and what they can find in turn. |
|
sbom
Package sbom describes a release's dependencies in a form other tools read.
|
Package sbom describes a release's dependencies in a form other tools read. |
|
semver
Package semver compares version tags.
|
Package semver compares version tags. |
|
sumdb
Package sumdb cross-checks a release's published source archive against sum.golang.org and the module proxy: see docs/hld/sumdb.md.
|
Package sumdb cross-checks a release's published source archive against sum.golang.org and the module proxy: see docs/hld/sumdb.md. |
|
updatecheck
Package updatecheck tells an interactive user, at most once per interval, that a newer letsgo release exists.
|
Package updatecheck tells an interactive user, at most once per interval, that a newer letsgo release exists. |
|
verify
Package verify rebuilds a published release and compares it against what was actually shipped.
|
Package verify rebuilds a published release and compares it against what was actually shipped. |
|
yank
Package yank retracts a published release.
|
Package yank retracts a published release. |
|
Package manifest describes a release in a form a machine can act on.
|
Package manifest describes a release in a form a machine can act on. |
|
Package plan is what a release plan says it will do.
|
Package plan is what a release plan says it will do. |
|
Package plugin is the SDK a letsgo plugin is written against.
|
Package plugin is the SDK a letsgo plugin is written against. |
|
Package selfupdate updates a binary released by letsgo, from inside that binary.
|
Package selfupdate updates a binary released by letsgo, from inside that binary. |