Cutting a release¶
moneta release releases a Go project in one command. It does not compile
anything itself:
moneta decides the version and writes the release notes, from the fragments that wait in
.changes, asmoneta nextandmoneta renderdo.mage builds the project. moneta runs your own mage target one time for each platform.
moneta then tags the release, packs the binaries, writes and signs the checksums, pushes the tag and publishes a GitLab release. It can also publish to Modrinth and announce on Discord.
You need git, mage, and sq if you sign releases.
Configure¶
The configuration is release: under moneta: in omniblack.yaml:
moneta:
release:
gitlab:
project: terryp/tool # optional with one GitLab remote
token-file: /run/user/1000/releaser-token
builds:
- binary: tool
platforms: [linux/amd64, linux/arm64, darwin/arm64]
archive:
format: tar.xz # tar.gz (default), tar.xz or zip
files: [LICENSE, README.md]
Do not mix it up with moneta.releases, which only makes the release
headings into links. moneta rejects a key of one in the other.
Key |
Default |
Meaning |
|---|---|---|
|
the last part of |
The name of the release when there are no modules |
|
|
The GitLab instance |
|
the remote’s project, when the repository has exactly one remote and it is on |
The project to publish to. With two remotes of any kind, such as a fork and its upstream, name it |
|
required |
A file that holds the API token |
|
the remote |
The remote to push the tag to |
|
none |
A mage target that runs before anything else in |
|
|
Sign the tag ( |
|
none |
The binaries to build. Top-level |
|
required |
The file name of the binary |
|
required |
|
|
|
The mage target that builds the binary |
|
the binary |
A name for the build in messages |
|
none |
A template for the name of a detached signature of each platform’s binary; see Sign each binary |
|
|
|
|
|
A template for the archive name, without the extension. With |
|
none |
A format for the builds of one OS, such as |
|
none |
More files to put in each archive. Not allowed with |
|
off |
Make a source archive of the whole repository too; see Source archive |
|
|
|
|
|
A template for the source archive’s name, without the extension |
|
none |
Archives of one directory each, with its contents at the root; see Extra source archives |
|
|
The name of the checksums file |
|
off |
Publish each release to a Modrinth project too; see Publish to Modrinth |
|
off |
Announce each release on Discord; see Announce on Discord |
The archive name template can use .Project, .Binary, .File, .Build,
.Module, .Version, .Tag, .Os and .Arch, and the functions lower,
upper and title, which every template in omniblack.yaml can use. moneta
rejects a template that gives two archives the same name.
.Binary is the name in builds[].binary. .File is the file the target
writes: the same, with .exe on Windows.
moneta checks the whole block every time it loads omniblack.yaml, not only
when you release. A misspelled key is an error at once.
A format per OS¶
Windows users expect a zip, and everyone else a tarball. format-overrides
sets the format for the builds of one OS:
moneta:
release:
archive:
format: tar.xz
format-overrides:
windows: zip
The keys are GOOS values, and each must be the OS of a build that the
archive packs. moneta rejects an override for an OS that nothing is built for,
so a typo such as widnows is an error. The values are tar.gz, tar.xz or
zip. An override cannot be none, and format: none takes no overrides.
any has no OS, so it cannot have an override either.
A module’s archive: replaces the top-level one completely, overrides
included.
Platform-independent builds¶
Some builds run on every platform, such as a jar or a script. For these, set
platforms: [any] and moneta builds one time:
moneta:
release:
builds:
- binary: mod.jar
platforms: [any]
moneta sets GOOS and GOARCH to empty values. Go reads an empty value as
unset, so a go build in the target builds for your machine. .Os and
.Arch are empty in the archive name, and the default name leaves them out:
this build makes mod.jar_1.2.3.tar.gz. any must be the only platform in
its list.
Publish the binary itself¶
A jar does not need to be in an archive. Set archive.format: none and moneta
publishes the binary as the mage target wrote it:
moneta:
release:
archive:
format: none
name: "mod_{{ .Version }}.jar" # optional
builds:
- binary: mod.jar
platforms: [any]
The target still writes to MONETA_BUILD_OUTPUT, which ends in mod.jar.
moneta then copies the file to dist/. With archive.name set, the copy gets
that name, and this example publishes mod_1.2.3.jar. moneta adds no
extension, except .exe for a Windows build. Without archive.name, the
binary keeps its own name, mod.jar.
The binary is listed in the checksums and signed with them, as an archive is.
A resumed release and --publish-only check it against the checksums too.
You cannot use archive.files here, because there is no archive to put them
in.
Each binary needs its own name. A build for two platforms with no
archive.name would publish two files with the same name, and moneta refuses
that configuration. Use platforms: [any], or put .Os and .Arch in the
name.
Sign each binary¶
The signed checksums cover every file of a release. Some clients check a
signature of the one file they use instead, such as a program that updates
itself and verifies the binary after it unpacks it. For those, give the build
a signature name:
moneta:
release:
builds:
- binary: tool
platforms: [linux/amd64, windows/amd64]
signature: "{{ .File }}_{{ .Os }}_{{ .Arch }}.sig"
moneta signs the binary that the target wrote, which is the same bytes as the
one in the archive, with sq sign --signer-self. It publishes the signature
under the name, here tool_linux_amd64.sig and tool.exe_windows_amd64.sig.
The template sees the same fields as archive.name. moneta rejects a template
that gives two signatures, or a signature and another file, the same name.
signature needs sign to be on. The signatures are made before the
checksums and listed in them, so a resumed release and --publish-only refuse
a dist/ where one is missing. A snapshot signs nothing.
sq runs once for each file it signs. If your key is locked, sq asks for its password each time: four binaries and the checksums are five prompts. moneta holds no key and no password, so it cannot ask only once. A key agent that keeps the key unlocked for a while can.
Source archive¶
Add a source: block to also release the source:
moneta:
release:
source:
format: tar.xz
source: {} turns it on with the defaults. A bare source: is empty in YAML,
so it does not turn it on.
The source archive holds the files that git archive gives for the released
commit. These are all the tracked files, without the files that
.gitattributes marks export-ignore. They are all in one directory with the
archive’s name. moneta packs the files itself, with the same fixed dates,
owners and modes as the binary archives, so the bytes do not change with the
git version. The archive goes in the checksums, is signed with them, and is
uploaded with the release.
GitLab shows source links on each release too. GitLab makes those files when someone downloads them, so their checksums can change and no signature covers them.
The source archive is made from the commit. In a snapshot of a tree with changes that are not committed, the binaries have the changes and the source archive does not.
The name template can use .Project, .Module, .Version and .Tag, and
the same functions as archive.name. .Module is empty in the archive of the
whole repository.
Extra source archives¶
Some projects ship one directory as source of its own, such as a website that
the binary downloads and builds. extra-sources makes an archive of one
directory at the released commit:
moneta:
release:
extra-sources:
- path: website-js
name: "tool-website-js_{{ .Version }}"
format: tar.xz
prefix: ""
files: [LICENSE]
sign: true
Key |
Default |
Meaning |
|---|---|---|
|
required |
A directory in the repository. The archive holds its contents relative to it, so |
|
required |
A template for the archive’s name, without the extension. It sees the same fields as |
|
|
|
|
the archive’s name |
The directory everything in the archive is under. |
|
none |
More files, relative to the repository root, packed at the root of the archive beside the directory’s contents |
|
|
Also publish a signature of the archive, under its name with |
The files are chosen as for the source archive: git archive of the commit, so only tracked files, without those marked
export-ignore. A node_modules directory that is not committed is not
packed. The files in files come from the commit too, not from your working
tree.
Before it tags anything, moneta checks that the commit has the directory and each file. An archive with nothing in it is an error. The archives and their signatures go in the checksums and are uploaded with the release.
A module can list its own extra-sources. They add to the top-level ones, so
every module’s release carries the top-level archives as well.
Write the mage target¶
moneta sets these variables, runs your target, and then checks that the
target wrote a file to MONETA_BUILD_OUTPUT:
Variable |
Value |
|---|---|
|
The platform, or empty for |
|
The version without the tag prefix, for example |
|
The full tag, for example |
|
The commit that is released |
|
The module, or empty |
|
The absolute path to write the binary to |
|
|
The buildenv package reads these variables for you:
import "gitlab.com/terryp/moneta/buildenv"
func Build() error {
env, ok := buildenv.FromEnv()
if !ok {
return sh.Run("go", "build", "-o", "dist/bin/tool", "./cmd/tool")
}
args := env.GoBuildArgs("./cmd/tool", "-X main.version="+env.Version)
return sh.RunWith(map[string]string{"CGO_ENABLED": "0"}, args[0], args[1:]...)
}
Name the target itself in mage-target, not a mage alias. moneta cannot find
an alias.
Release¶
$ moneta release --plan # what each module would release
$ moneta snapshot # build and pack; no tag, nothing published
$ moneta release --dry-run # everything up to the push, then delete the tag
$ moneta release
release does these steps in this order:
It checks that the working tree is clean, then runs the
before-targetif you set one. The tree must still be clean after the target.It checks the token, and the Discord webhook if you set one.
For each module, it works out the next version, checks the mage targets, and runs the module’s
before-target. If no fragment waits, it stops. Withmodrinthset, it reads the game versions, and finds the project and its dependencies on Modrinth. Then, if sign is on and a module has files, it checks forsq.It makes the tag, but only in your clone.
It renders the notes, builds each platform with mage, packs the archives, signs each binary that has a
signaturename, and writes and signs the checksums.It pushes the tag.
It uploads the files to the GitLab project’s uploads and creates the release, with a link to each file. If a release for the tag exists, moneta replaces it.
If
modrinthis set, it sets the project’s description frombody-from, when that is set, and creates the version on Modrinth, unless the version is there already.If
announce.discordis set, it posts the release to Discord.
If a step before the push fails, moneta deletes the tag, so nobody else sees it.
If a run stops after the tag exists, run moneta release again. This applies
if the run was killed, the push or the publish failed, or you made the tag
yourself. On a HEAD that has the release tag, moneta finishes that release and
does only the steps that are not done:
It uses the tag that is there, and never deletes it.
It reuses
dist/if the archives agree with the checksums. If not, it builds, packs and signs again.It pushes the tag if the remote does not have it. It stops if the remote has the tag on a different object.
It publishes the release if GitLab does not have it. If the release exists, moneta does nothing, unless the version is missing on Modrinth; see Publish to Modrinth.
With sign: true, a tag that is not pushed yet must be signed.
moneta release --publish-only is the strict retry. It publishes the release
that is tagged on HEAD from the files in dist/. It never builds and never
runs a before-target. It refuses files that do not agree with the
checksums, and it replaces a GitLab release that exists. It never replaces a
Modrinth version. It does not announce the release, so a retry never posts
twice.
Add dist/ to .gitignore. moneta writes its output there.
Publish to Modrinth¶
moneta can publish each release to Modrinth as a version of a project, so a Minecraft mod has no second upload step in Gradle:
moneta:
release:
archive:
format: none
builds:
- binary: immortal_bees.jar
platforms: [any]
modrinth:
project: immortal-bees
token-file: /run/user/1000/modrinth-token
game-versions-from:
file: gradle.properties
key: minecraft_version
loaders: [fabric]
dependencies:
- project: fabric-api
type: required
Key |
Default |
Meaning |
|---|---|---|
|
required |
The project’s slug or ID |
|
required |
A file that holds a Modrinth personal access token that can create versions |
|
required |
The mod loaders, such as |
|
A list of game versions. Set this or |
|
|
A |
|
|
none |
Projects by slug or ID, each with a |
|
|
Mark the version as featured |
|
|
A template for the version’s title. It can use |
|
every build but |
The ids of the builds to upload. The first one is the primary file |
|
off |
The id of a build whose output becomes the project’s description; see Project description |
|
|
The API. |
moneta sets the rest from the release:
The version number is the version without the tag prefix, such as
1.3.0.The changelog is the release notes.
The version type comes from the version. A prerelease that starts with
alphais an alpha, one that starts withbetaorrcis a beta, and any other version is a release.
Modrinth takes one file for a mod, not one per platform, so each build that
goes to Modrinth must be platforms: [any]. With archive.format: none,
moneta uploads the binary it publishes. With an archive, moneta also copies
the binary into dist/ under its own name, such as immortal_bees.jar, and
lists it in the checksums beside the archive.
Game versions¶
game-versions-from reads the game versions from the file your build reads
them from, so the two cannot disagree. moneta reads the file at the commit it
releases, not in the working tree. A value with commas, such as
1.21.4, 1.21.5, names more than one version.
moneta reads the file before it makes the tag, and stops if the file or the
key is missing or the value is empty. release --plan and
release --dry-run show the versions they found. moneta reads the parts of
the .properties format that Gradle files use: key=value, key: value,
# and ! comments, and \ at the end of a line. It refuses a \uXXXX
escape; write the character itself.
Project description¶
moneta can also set the project’s description on Modrinth to a file your
build writes, so the page cannot fall behind the mod. Add a build for it and
name it in body-from:
moneta:
release:
builds:
- binary: immortal_bees.jar
platforms: [any]
- id: description
binary: MODRINTH.md
mage-target: modrinthDescription
platforms: [any]
modrinth:
body-from: description
# ...
The target writes the description to $MONETA_BUILD_OUTPUT, as any build
does. It must be platforms: [any]. moneta does not upload it to the
version. It publishes the file under its own name, MODRINTH.md, whatever
archive.format is, and lists it in the checksums and on the GitLab release.
moneta sends the file as it is. Modrinth does not resolve a link or an image relative to your repository, so use full URLs. An empty file stops the release.
moneta sets the description on every run that publishes to Modrinth,
--publish-only included, and before it creates the version. So a failed
update is retried with the version, by running release again. The token
needs the Write projects scope as well as Create versions.
Retries¶
A Modrinth version is not replaced, because deleting a version loses its
downloads and breaks what depends on it. moneta looks for the version before
it creates one, for the module’s loaders. If the version is there, moneta
leaves it alone and says so in the log. That includes --publish-only.
If the Modrinth step fails, the release is on GitLab but not on Modrinth, and
it is not announced yet. Run moneta release again. moneta leaves the GitLab
release alone, uploads the files from dist/, and then announces the
release. It does not build the files again, because the GitLab release lists
the ones it built, so dist/ must still hold them.
release --dry-run shows the request it would send, without the token, and
sends nothing. A snapshot does not publish to Modrinth.
With modules, a module’s modrinth: replaces the top-level one. A module
without one uses the top-level block.
Announce on Discord¶
moneta can post each release to a Discord channel when the release is published:
moneta:
release:
announce:
discord:
webhook-file: /run/user/1000/discord-webhook
Make a webhook in the channel’s settings (Integrations, then Webhooks) and put its URL in the file. The URL holds the webhook’s token, so it goes in a file, as the GitLab token does, and moneta never prints it.
Key |
Default |
Meaning |
|---|---|---|
|
required |
A file that holds the webhook’s URL |
|
|
A template for the text above the notes |
|
the webhook’s name |
The name the message is posted under |
|
the webhook’s picture |
The picture the message is posted under |
|
|
The colour of the post’s edge, as |
The post is one embed. Its title is the tag and links to the release page.
Its body is the message, then the release notes. Discord takes at most 4096
characters there, so moneta cuts longer notes at a line break and adds a link
to the full notes. The release page is moneta.releases.url if you set it,
and the GitLab release otherwise.
username and avatar-url change the name and picture at the top of the
message, for that message only. Unset, Discord shows the webhook’s own, which
you set in the webhook’s settings. With them, one webhook can post as each
project that uses it. Discord refuses a name that holds “discord” or “clyde”,
or is longer than 80 characters, so moneta checks for that when it loads the
configuration.
The message template can use .Project, .Module, .Version, .Tag and
.URL, the release page.
release --dry-run shows the message in its log and posts nothing. A
snapshot does not announce.
The post is the last step, after the release is public. If it fails, moneta
reports an error and the release stays. Run
moneta release --announce-only to post it. That needs the release tag on
HEAD and the release on GitLab, and on Modrinth if you set modrinth. It
does nothing else.
announce is for the whole repository. With modules, each module’s release
is posted to the same webhook, and .Module tells them apart.
Modules¶
A repository can release more than one thing. Put each module’s builds in a
release: block under the module’s moneta::
modules:
- name: core
path: core
moneta:
release:
builds:
- binary: core
platforms: [linux/amd64, darwin/arm64]
- name: cli
tag-prefix: cli/v
moneta:
release:
archive:
format: zip
builds:
- binary: cli
platforms: [linux/amd64, windows/amd64]
moneta:
release:
gitlab:
project: terryp/tool
token-file: /run/user/1000/releaser-token
archive:
format: tar.xz
A module’s block can hold builds, archive, source, checksum and
before-target. The top-level block keeps the settings of the whole project:
gitlab, sign, project, its own before-target, source, and the
default archive and checksum. When a module has its own archive, it
replaces the top-level one completely. It does not merge with it.
source is different. The top-level source makes an archive of the whole
repository, and the release of each module includes it. A module’s own
source makes a second archive in that module’s release, with only the files
in the module’s path. A module that has no path gets the whole repository
again. With the default names, the two archives are tool_1.2.0_source and
tool-core_1.2.0_source. For module archives only, put source in the blocks
of those modules and not at the top level.
A module’s before-target runs in addition to the top-level one, for
example to run the linters of that module only. The top-level target runs
first, one time. Then each module’s target runs, before any module is tagged,
so a failure in the last module stops the release of all of them. A target
runs one time in a run, even if more than one module names it. The target of
a module that is skipped because no fragment waits does not run.
With modules, a build in the top-level builds is an error, because it would
have no module’s tag to release under.
moneta releases a module only if its moneta: has a release: block. A
module without a block is not released, and --all skips it. A module does
not need builds. For example, release: {} releases the tag and notes of a
docs module. A bare release: with no value is YAML’s null, and is the same
as no block.
Name the module with --module (-M), or release all modules with --all.
release and snapshot do not use $MONETA_MODULE or the directory, as the
commands that read a changelog do: a release cannot be taken back, so you name
it. --all skips a module that has no fragments waiting. Each module gets its
own tag (core/v1.2.0) and its own archives in dist/<module>/.
Releases without builds¶
A release with no builds and no source has no files. It is the tag and a
GitLab release with the notes. It has no checksums file and no signature,
because a signature over an empty list proves nothing. With sign: true the
tag is signed, and sq is not needed. A release with only a source archive
has checksums and a signature as usual.
Moving from capyreleaser¶
moneta release was a separate tool, capyreleaser. moneta stops with an
error that names the new place of a capyreleaser: block. To move:
Move the top-level
capyreleaser:block undermoneta:asrelease:.In each module entry, move its
capyreleaser:block under the module’smoneta:asrelease:.In your magefile, import
gitlab.com/terryp/moneta/buildenvinstead ofgitlab.com/terryp/capyreleaser/buildenv. A magefile that reads the variables itself must use theMONETA_BUILD_names above instead ofCAPY_.Replace
capyreleaser checkwithmoneta release --plan. The other commands keep their names and flags.