Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 135 additions & 37 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,44 +1,142 @@
name: Release

# Generated by chant — do not edit directly. Regenerate with: chant release workflow --forge github (in the workspace root)
name: chant release
on:
push:
tags:
- "v*"

workflow_dispatch:
inputs:
label:
description: The release's label, such as v1.4.0, or auto for the one chant release next computes
required: true
type: string
permissions:
contents: write
packages: write

contents: read
concurrency:
group: chant-release
cancel-in-progress: false
env:
CHANT_RELEASE_LABEL: ${{ inputs.label }}
jobs:
goreleaser:
name: GoReleaser
gate:
runs-on: ubuntu-latest
permissions:
contents: read
outputs:
commit: ${{ steps.green.outputs.commit }}
label: ${{ steps.green.outputs.label }}
steps:
- uses: actions/checkout@v7
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
fetch-depth: 0

- uses: actions/setup-go@v6
with:
go-version: "1.25"

- name: Set up QEMU
uses: docker/setup-qemu-action@v3

- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v4

- name: Log in to GHCR
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}

- name: Run GoReleaser
uses: goreleaser/goreleaser-action@v6
with:
version: "~> v2"
args: release --clean
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
with:
node-version: 24
registry-url: https://registry.npmjs.org
- run: git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'
- id: green
run: |
commit="$GITHUB_SHA"
label="$CHANT_RELEASE_LABEL"; if [ "$label" = auto ]; then rc=0; git ls-remote --exit-code --heads origin chant/lifecycle >/dev/null || rc=$?; if [ "$rc" = 0 ]; then git fetch origin chant/lifecycle:chant/lifecycle; elif [ "$rc" != 2 ]; then exit "$rc"; fi; next="$(npx --yes @intentius/chant@0.124.104 release next --at "$commit" --json)" || { echo "release next found no label for $commit, so no release is cut: $next" >&2; exit 1; }; label="$(printf '%s' "$next" | node -e 'const f=process.argv[1];const t=f?require("fs").readFileSync(f,"utf8"):require("fs").readFileSync(0,"utf8");const d=JSON.parse(t);process.stdout.write(String(d.label??""))')"; fi
echo "commit=$commit" >> "$GITHUB_OUTPUT"
echo "label=$label" >> "$GITHUB_OUTPUT"
cut:
needs: gate
runs-on: ubuntu-latest
permissions:
contents: write
checks: read
statuses: read
env:
CHANT_RELEASE_COMMIT: ${{ needs.gate.outputs.commit }}
CHANT_RELEASE_LABEL: ${{ needs.gate.outputs.label }}
GITHUB_TOKEN: ${{ github.token }}
CHANT_RELEASE_GIT_TOKEN: ${{ github.token }}
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: credential.${{ github.server_url }}.helper
GIT_CONFIG_VALUE_0: "!f() { test \"$1\" = get && echo username=x-access-token && echo \"password=$CHANT_RELEASE_GIT_TOKEN\"; }; f"
OCI_USERNAME: "${{ github.actor }}"
OCI_PASSWORD: "${{ github.token }}"
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
ref: ${{ needs.gate.outputs.commit }}
fetch-depth: 0
persist-credentials: false
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
with:
node-version: 24
registry-url: https://registry.npmjs.org
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version-file: "go.mod"
cache: false
- uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0
with:
platforms: "arm64"
- run: npx --yes @intentius/chant@0.124.104 release doctor
- name: goreleaser v2.19.0
run: "mkdir -p \"$RUNNER_TEMP/goreleaser\" && curl -fsSL -o \"$RUNNER_TEMP/goreleaser/goreleaser.tar.gz\" https://github.com/goreleaser/goreleaser/releases/download/v2.19.0/goreleaser_Linux_x86_64.tar.gz && echo \"ebc3194ad1d1b1787614405285a0039665cd4c5bd3305215a1b201600f90630b $RUNNER_TEMP/goreleaser/goreleaser.tar.gz\" | sha256sum -c - && tar -xzf \"$RUNNER_TEMP/goreleaser/goreleaser.tar.gz\" -C \"$RUNNER_TEMP/goreleaser\" goreleaser && echo \"CHANT_GORELEASER=$RUNNER_TEMP/goreleaser/goreleaser\" >> \"$GITHUB_ENV\""
- run: git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'
- run: rc=0; git ls-remote --exit-code --heads origin chant/lifecycle >/dev/null || rc=$?; if [ "$rc" = 0 ]; then git fetch origin chant/lifecycle:chant/lifecycle; elif [ "$rc" != 2 ]; then exit "$rc"; fi
- run: |
git config user.name "chant release"
git config user.email "chant-release@localhost"
npx --yes @intentius/chant@0.124.104 release cut "$CHANT_RELEASE_LABEL" --at "$CHANT_RELEASE_COMMIT" --yes --json > "$RUNNER_TEMP/chant-cut.json"
tag="$(node -e 'const f=process.argv[1];const t=f?require("fs").readFileSync(f,"utf8"):require("fs").readFileSync(0,"utf8");const d=JSON.parse(t);process.stdout.write(String(d.tag?.name??""))' "$RUNNER_TEMP/chant-cut.json")"
if [ -n "$tag" ]; then git push origin "refs/tags/$tag"; fi
- run: npx --yes @intentius/chant@0.124.104 release artifacts "$CHANT_RELEASE_LABEL" --no-build -o "$RUNNER_TEMP/chant-release-artifacts"
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: chant-release-artifacts
path: ${{ runner.temp }}/chant-release-artifacts
if-no-files-found: error
retention-days: 1
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: chant-release-images
path: |
build/images/mudflaps.tar
if-no-files-found: error
retention-days: 1
publish:
needs: [gate, cut]
runs-on: ubuntu-latest
permissions:
contents: write
id-token: write
packages: write
checks: read
statuses: read
env:
CHANT_RELEASE_LABEL: ${{ needs.gate.outputs.label }}
GITHUB_TOKEN: ${{ github.token }}
OCI_USERNAME: "${{ github.actor }}"
OCI_PASSWORD: "${{ github.token }}"
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
ref: ${{ needs.gate.outputs.commit }}
fetch-depth: 0
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
with:
node-version: 24
registry-url: https://registry.npmjs.org
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version-file: "go.mod"
cache: false
- uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0
with:
platforms: "arm64"
- run: git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'
- run: git fetch origin chant/lifecycle:chant/lifecycle
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
with:
name: chant-release-images
path: build/images
- run: npx --yes @intentius/chant@0.124.104 release images "$CHANT_RELEASE_LABEL" --no-build -o "$RUNNER_TEMP/chant-release-digests.json"
- run: echo "CHANT_RELEASE_DIGESTS=$RUNNER_TEMP/chant-release-digests.json" >> "$GITHUB_ENV"
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
with:
name: chant-release-artifacts
path: ${{ runner.temp }}/chant-release-artifacts
- run: npx --yes @intentius/chant@0.124.104 release artifacts "$CHANT_RELEASE_LABEL" --from "$RUNNER_TEMP/chant-release-artifacts"
- run: npx --yes @intentius/chant@0.124.104 release publish "$CHANT_RELEASE_LABEL" --yes
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -24,3 +24,6 @@ go.work.sum

# mkdocs build output
/site/

# chant release: container image archives the cut builds (build/images)
/build/
52 changes: 7 additions & 45 deletions .goreleaser.yaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
# GoReleaser configuration. See https://goreleaser.com
#
# `chant release cut` runs this in snapshot mode (goreleaser release --snapshot
# --clean --skip=publish) and records the archives and checksums it writes; chant
# publishes them and the container image (see chant.config.json and RELEASING.md).
version: 2

project_name: mudflaps
Expand Down Expand Up @@ -39,52 +43,10 @@ archives:
checksum:
name_template: checksums.txt

dockers:
- image_templates:
- "ghcr.io/intentius/mudflaps:{{ .Version }}-amd64"
dockerfile: Dockerfile.goreleaser
use: buildx
goos: linux
goarch: amd64
build_flag_templates:
- "--platform=linux/amd64"
- "--build-arg=VERSION={{ .Version }}"
- "--label=org.opencontainers.image.source=https://github.com/intentius/mudflaps"
- "--label=org.opencontainers.image.version={{ .Version }}"
- "--label=org.opencontainers.image.licenses=MIT"
- image_templates:
- "ghcr.io/intentius/mudflaps:{{ .Version }}-arm64"
dockerfile: Dockerfile.goreleaser
use: buildx
goos: linux
goarch: arm64
build_flag_templates:
- "--platform=linux/arm64"
- "--build-arg=VERSION={{ .Version }}"
- "--label=org.opencontainers.image.source=https://github.com/intentius/mudflaps"
- "--label=org.opencontainers.image.version={{ .Version }}"
- "--label=org.opencontainers.image.licenses=MIT"

docker_manifests:
- name_template: "ghcr.io/intentius/mudflaps:{{ .Version }}"
image_templates:
- "ghcr.io/intentius/mudflaps:{{ .Version }}-amd64"
- "ghcr.io/intentius/mudflaps:{{ .Version }}-arm64"
- name_template: "ghcr.io/intentius/mudflaps:latest"
image_templates:
- "ghcr.io/intentius/mudflaps:{{ .Version }}-amd64"
- "ghcr.io/intentius/mudflaps:{{ .Version }}-arm64"

changelog:
use: github
sort: asc
filters:
exclude:
- "^docs:"
- "^test:"
- "^chore:"

release:
github:
owner: intentius
name: mudflaps

snapshot:
version_template: "{{ .Env.CHANT_RELEASE_LABEL }}"
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,4 +56,4 @@ see [SECURITY.md](./SECURITY.md) instead of filing a public issue.

## Releasing

Maintainers: see [RELEASING.md](./RELEASING.md). Releases are tag-driven — `just release X.Y.Z` from a clean `main`.
Maintainers: see [RELEASING.md](./RELEASING.md). Releases go through `chant release`: `just release X.Y.Z` from a clean `main` starts the Release workflow, which cuts and tags the newest green commit.
6 changes: 3 additions & 3 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,8 @@ docs-build:
docs-serve:
mkdocs serve

# Cut a release: preflight, then tag and push vV. Usage: make release V=0.2.0
# Start a release: preflight, then dispatch the Release workflow, where chant
# cuts and publishes vV. Usage: make release V=0.6.0
# (`just release 0.2.0` is the primary path; see RELEASING.md.)
release:
@test -n "$(V)" || { echo "usage: make release V=X.Y.Z"; exit 1; }
Expand All @@ -52,5 +53,4 @@ release:
git pull --ff-only origin main
@grep -q "## \[$(V)\]" CHANGELOG.md || { echo "CHANGELOG.md has no '## [$(V)]' section"; exit 1; }
go build ./... && go vet ./... && test -z "$$(gofmt -l .)" && go test ./...
git tag -a "v$(V)" -m "mudflaps v$(V)"
git push origin "v$(V)"
gh workflow run release.yml --repo INTENTIUS/mudflaps --ref main -f label=$(V)
42 changes: 34 additions & 8 deletions RELEASING.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,53 @@
# Releasing

mudflaps releases are tag-driven: pushing a `vX.Y.Z` tag triggers the
[Release workflow](.github/workflows/release.yml), which runs GoReleaser to build
the binaries, the checksums, and the multi-arch container image, publishes a
GitHub Release, and pushes the image to `ghcr.io/intentius/mudflaps`.
mudflaps releases with [`chant release`](https://intentius.io/chant/cli/release/).
A release is started by hand: the [Release workflow](.github/workflows/release.yml)
picks the newest green commit of `main`, cuts it as `vX.Y.Z`, and publishes:

- a GitHub Release `vX.Y.Z` with the GoReleaser archives for linux, darwin and
windows on amd64 and arm64 (`.tar.gz`, `.zip` on windows) and `checksums.txt`,
with notes generated from the conventional commits since the previous release;
- the multi-arch (linux/amd64, linux/arm64) container image
`ghcr.io/intentius/mudflaps:X.Y.Z`, with `latest` moved to it and `X.Y.Z-amd64` and `X.Y.Z-arm64` for each platform.

The release is configured in [`chant.config.json`](chant.config.json). The cut
runs GoReleaser in snapshot mode (`.goreleaser.yaml`) for the binaries, archives
and checksums, builds the image from the top-level `Dockerfile`, records every
file by digest, and pushes the tag. The publish job then uploads exactly those
files and that image. Tags stay `vX.Y.Z`; the `v*` tags from before chant are
read as the release history.

`release.yml` is generated: change `chant.config.json`, then regenerate it with

```sh
npx --yes @intentius/chant@0.124.104 release workflow --force
```

## Steps

1. **Update the changelog.** In `CHANGELOG.md`, move the `## [Unreleased]` items
into a new `## [X.Y.Z] - YYYY-MM-DD` section and refresh the link references at
the bottom. Commit it to `main` (via PR).
the bottom. Commit it to `main` (via PR) and let CI go green.

2. **Check the label** (optional). From a clean, up-to-date `main`:

```sh
npx --yes @intentius/chant@0.124.104 release next # the label the commits give
```

2. **Cut the release** from a clean `main`:
3. **Start the release:**

```sh
just release X.Y.Z # or: make release V=X.Y.Z
```

The recipe refuses to proceed unless the working tree is clean, you are on
`main`, the changelog has a `## [X.Y.Z]` section, and `build`/`vet`/`gofmt`/
`test` all pass. It then tags `vX.Y.Z` and pushes the tag.
`test` all pass. It then dispatches the Release workflow with the label
`X.Y.Z`. `gh workflow run release.yml -f label=auto` takes the label from the
commits instead.

3. **Watch the release build:**
4. **Watch the release build:**

```sh
gh run watch --repo INTENTIUS/mudflaps
Expand Down
40 changes: 40 additions & 0 deletions chant.config.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
{
"release": {
"tag": "v{version}",
"legacyTags": ["v"],
"green": "forge-checks",
"images": [
{
"name": "mudflaps",
"dockerfile": "Dockerfile",
"args": { "VERSION": "{version}" },
"labels": {
"org.opencontainers.image.source": "https://github.com/intentius/mudflaps",
"org.opencontainers.image.version": "{version}",
"org.opencontainers.image.licenses": "MIT"
}
}
],
"artifacts": [{ "name": "goreleaser", "goreleaser": {} }],
"publish": [
{
"type": "forge",
"forge": "github",
"repo": "INTENTIUS/mudflaps",
"assets": ["artifact:goreleaser"],
"notes": { "generate": "commits", "exclude": ["docs", "test", "chore"] }
},
{
"type": "oci",
"image": "build/images/mudflaps.tar",
"repository": "ghcr.io/intentius/mudflaps",
"tags": ["{label}", "latest"],
"platformTags": ["{version}-{arch}"]
}
],
"workflow": {
"trigger": "dispatch",
"file": ".github/workflows/release.yml"
}
}
}
Loading
Loading