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, as moneta next and moneta render do.

  • 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

project

the last part of gitlab.project

The name of the release when there are no modules

gitlab.url

https://gitlab.com

The GitLab instance

gitlab.project

the remote’s project, when the repository has exactly one remote and it is on gitlab.url’s host

The project to publish to. With two remotes of any kind, such as a fork and its upstream, name it

gitlab.token-file

required

A file that holds the API token

gitlab.remote

the remote gitlab.project was read from, else origin

The remote to push the tag to

before-target

none

A mage target that runs before anything else in release, release --dry-run and snapshot, such as your lint-and-test gate. A module can have its own; see Modules

sign

true

Sign the tag (git tag -s) and the checksums (sq sign --signer-self)

builds

none

The binaries to build. Top-level builds is for a repository without modules; see Modules. With no builds, a release has only the tag, the notes and the source archive, if you set one; see Releases without builds

builds[].binary

required

The file name of the binary

builds[].platforms

required

GOOS/GOARCH pairs, or any alone for one build that runs on every platform; see Platform-independent builds

builds[].mage-target

build

The mage target that builds the binary

builds[].id

the binary

A name for the build in messages

builds[].signature

none

A template for the name of a detached signature of each platform’s binary; see Sign each binary

archive.format

tar.gz

tar.gz, tar.xz, zip, or none to publish each binary without an archive; see Publish the binary itself

archive.name

{{ .Binary }}_{{ .Version }}{{ with .Os }}_{{ . }}{{ end }}{{ with .Arch }}_{{ . }}{{ end }}

A template for the archive name, without the extension. With format: none, the name to publish the binary under, and unset, the binary’s own name

archive.format-overrides

none

A format for the builds of one OS, such as windows: zip; see A format per OS

archive.files

none

More files to put in each archive. Not allowed with format: none

source

off

Make a source archive of the whole repository too; see Source archive

source.format

tar.gz

tar.gz, tar.xz or zip

source.name

{{ .Project }}{{ with .Module }}-{{ . }}{{ end }}_{{ .Version }}_source

A template for the source archive’s name, without the extension

extra-sources

none

Archives of one directory each, with its contents at the root; see Extra source archives

checksum

checksums.txt

The name of the checksums file

modrinth

off

Publish each release to a Modrinth project too; see Publish to Modrinth

announce.discord

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

path

required

A directory in the repository. The archive holds its contents relative to it, so website-js/package.json is packed as package.json

name

required

A template for the archive’s name, without the extension. It sees the same fields as source.name; .Module is the module being released

format

tar.gz

tar.gz, tar.xz or zip

prefix

the archive’s name

The directory everything in the archive is under. "" puts the files at the root

files

none

More files, relative to the repository root, packed at the root of the archive beside the directory’s contents

sign

false

Also publish a signature of the archive, under its name with .sig. Needs sign on

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

GOOS, GOARCH

The platform, or empty for platforms: [any]

MONETA_BUILD_VERSION

The version without the tag prefix, for example 1.2.3

MONETA_BUILD_TAG

The full tag, for example core/v1.2.3

MONETA_BUILD_COMMIT

The commit that is released

MONETA_BUILD_MODULE

The module, or empty

MONETA_BUILD_OUTPUT

The absolute path to write the binary to

MONETA_BUILD_SNAPSHOT

1 in a snapshot

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:

  1. It checks that the working tree is clean, then runs the before-target if you set one. The tree must still be clean after the target.

  2. It checks the token, and the Discord webhook if you set one.

  3. 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. With modrinth set, 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 for sq.

  4. It makes the tag, but only in your clone.

  5. It renders the notes, builds each platform with mage, packs the archives, signs each binary that has a signature name, and writes and signs the checksums.

  6. It pushes the tag.

  7. 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.

  8. If modrinth is set, it sets the project’s description from body-from, when that is set, and creates the version on Modrinth, unless the version is there already.

  9. If announce.discord is 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

project

required

The project’s slug or ID

token-file

required

A file that holds a Modrinth personal access token that can create versions

loaders

required

The mod loaders, such as fabric

game-versions

A list of game versions. Set this or game-versions-from

game-versions-from.file, .key

A .properties file in the repository and the key to read the game versions from

dependencies

none

Projects by slug or ID, each with a type: required, optional, incompatible or embedded

featured

false

Mark the version as featured

name

{{ .Project }} {{ .Version }}

A template for the version’s title. It can use .Project, .Module, .Version and .Tag

files

every build but body-from

The ids of the builds to upload. The first one is the primary file

body-from

off

The id of a build whose output becomes the project’s description; see Project description

url

https://api.modrinth.com/v2

The API. https://staging-api.modrinth.com/v2 is Modrinth’s sandbox

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 alpha is an alpha, one that starts with beta or rc is 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

webhook-file

required

A file that holds the webhook’s URL

message

{{ .Project }}{{ with .Module }} {{ . }}{{ end }} {{ .Tag }} is out!

A template for the text above the notes

username

the webhook’s name

The name the message is posted under

avatar-url

the webhook’s picture

The picture the message is posted under

color

3888754

The colour of the post’s edge, as 0xRRGGBB in decimal

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:

  1. Move the top-level capyreleaser: block under moneta: as release:.

  2. In each module entry, move its capyreleaser: block under the module’s moneta: as release:.

  3. In your magefile, import gitlab.com/terryp/moneta/buildenv instead of gitlab.com/terryp/capyreleaser/buildenv. A magefile that reads the variables itself must use the MONETA_BUILD_ names above instead of CAPY_.

  4. Replace capyreleaser check with moneta release --plan. The other commands keep their names and flags.