Day 7: Releases
Goal: A Git tag
v0.5.0triggers a GitHub release with binaries, checksums and release notes – and an image with a version number. · Duration: approx. 60 min · Prerequisite: Day 6
Briefing
- A release on GitHub is attached to a Git tag:
title, body, attached files (“assets”).
gh release createcreates it – in a workflow too. - The
pushtrigger withtags: ['v*']starts a workflow for every new tag that begins withv.GITHUB_REF_NAMEthen contains the tag name. - For releases, the
GITHUB_TOKENneedscontents: write. metadata-actionturnsv0.5.1into the image tags0.5.1and0.5.
git push origin v0.5.0
├─► release.yml: build amd64/arm64 ─► SHA256SUMS ─► gh release create v0.5.0
└─► image.yml: ghcr.io/<du>/notes-api:0.5.0, :0.5
Drill 1: The release workflow
cd ~/gha-lab/notes-actions
cat > .github/workflows/release.yml <<'EOF'
name: release
on:
push:
tags: ['v*']
permissions:
contents: write
jobs:
build:
strategy:
matrix:
goarch: [amd64, arm64]
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v7
- uses: actions/setup-go@v7
with:
go-version-file: go.mod
- name: Bauen
env:
CGO_ENABLED: "0"
GOOS: linux
GOARCH: ${{ matrix.goarch }}
run: >-
go build -trimpath -ldflags "-s -w -X main.version=${GITHUB_REF_NAME#v}"
-o notes-api-linux-$GOARCH .
- uses: actions/upload-artifact@v7
with:
name: notes-api-linux-${{ matrix.goarch }}
path: notes-api-linux-${{ matrix.goarch }}
release:
needs: build
runs-on: ubuntu-24.04
steps:
- uses: actions/download-artifact@v8
with:
pattern: notes-api-linux-*
merge-multiple: true
- name: Prüfsummen
run: sha256sum notes-api-linux-* > SHA256SUMS
- name: Release anlegen
env:
GH_TOKEN: ${{ github.token }}
run: >-
gh release create "$GITHUB_REF_NAME" notes-api-linux-* SHA256SUMS
--repo "$GITHUB_REPOSITORY" --generate-notes
EOF
git add .github
git commit -qm "release: Workflow für Tags"
git push -q${GITHUB_REF_NAME#v}is Bash:v0.5.0becomes0.5.0.pattern:withmerge-multiple: truedownloads all matching artifacts into one folder – withoutmerge-multiple, each would get a subfolder of its own.ghis preinstalled on GitHub’s runners. It reads the token fromGH_TOKEN.github.tokenis the same assecrets.GITHUB_TOKEN.--generate-noteswrites the release notes from the pull requests since the last release.
Set and push the tag:
git tag v0.5.0
git push -q origin v0.5.0
gh run list --workflow release.yml --limit 1Expected (after a few seconds):
STATUS TITLE WORKFLOW BRANCH EVENT ID ELAPSED AGE
* release: Workflow für Tags release v0.5.0 push 41618966812 17s now
BRANCH shows the tag name, the title is the message of
the tagged commit.
As soon as the run is finished:
gh release view v0.5.0Expected (shortened):
v0.5.0
github-actions[bot] released this less than a minute ago
## What's Changed
• version: 0.5.0-dev als Vorgabe by @<du> in https://github.com/<du>/notes-...
• ci: PR-Info by @<du> in https://github.com/<du>/notes-actions/pull/2
...
## New Contributors
• @<du> made their first contribution in https://github.com/<du>/notes-act...
Full Changelog: https://github.com/<du>/notes-actions/commits/v0.5.0
Assets
NAME DIGEST SIZE
notes-api-linux-amd64 sha256:73106061af9524e98fa9fb48fb72591a5902... 11.17 MiB
notes-api-linux-arm64 sha256:b93de8fc4036ee96aa7827e3a7b888be4032... 10.56 MiB
SHA256SUMS sha256:7e20345bdf53b123fdf9de7b97b3f6dba3c9... 176 B
The publisher is github-actions[bot] – the account
behind the GITHUB_TOKEN.
Save your progress? Sign up for free
Drill 2: Downloading and verifying
mkdir -p ~/gha-lab/rel
cd ~/gha-lab/rel
gh release download v0.5.0 -R <du>/notes-actions \
-p notes-api-linux-amd64 -p SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMSExpected:
notes-api-linux-amd64: OK
-pselects assets by pattern. Several-pare allowed.--ignore-missingchecks only the files that are present – you did not download the arm64 file.
The version is baked into the binary:
chmod +x notes-api-linux-amd64
NOTES_API_KEY=lab-api-key-123 PORT=8090 ./notes-api-linux-amd64 &
curl -s localhost:8090/version
kill %1Expected (with log lines from notes-api in between):
0.5.0
chmod +x, because release assets – unlike artifacts
fetched with gh run download – arrive without execute
permission.
Save your progress? Sign up for free
Drill 3: Images with a version number
image.yml should also run on tags and assign version
tags. The new file (changed: tags: under push,
two type=semver lines):
cd ~/gha-lab/notes-actions
cat > .github/workflows/image.yml <<'EOF'
name: image
on:
push:
branches: [main]
tags: ['v*']
paths-ignore: ['**.md']
pull_request:
workflow_dispatch:
permissions:
contents: read
packages: write
jobs:
image:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v7
- uses: docker/setup-buildx-action@v4
- if: github.event_name != 'pull_request'
uses: docker/login-action@v4
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- id: meta
uses: docker/metadata-action@v6
with:
images: ghcr.io/${{ github.repository_owner }}/notes-api
tags: |
type=ref,event=branch
type=ref,event=pr
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=sha
- uses: docker/build-push-action@v7
with:
context: .
platforms: linux/amd64,linux/arm64
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
build-args: |
VERSION=${{ steps.meta.outputs.version }}
REVISION=${{ github.sha }}
cache-from: type=gha
cache-to: type=gha,mode=max
EOF
git commit -qam "image: Versions-Tags"
git push -q
git tag v0.5.1
git push -q origin v0.5.1type=semver,pattern={{version}}turns the Git tagv0.5.1into the image tag0.5.1.{{major}}.{{minor}}yields0.5– a tag that always points to the latest patch of the series.semveronly applies to tags. For pushes tomain, the line produces nothing.paths-ignoredoes not apply to tags – a tag push always starts the workflow.
As soon as the run from
gh run list --workflow image.yml --limit 1 is finished:
gh api /user/packages/container/notes-api/versions \
--jq '.[].metadata.container.tags | select(index("0.5.1"))'Expected:
["latest","0.5","0.5.1"]
select(index("0.5.1"))keeps only the version whose tag list contains0.5.1.- You did not ask for
latest:metadata-actionassigns it on its own as soon as asemvertag is created. If you don’t want that, setflavor: latest=false.
docker run --rm -d --name notes-gha -p 8091:8080 -e NOTES_API_KEY=lab-api-key-123 \
ghcr.io/<du>/notes-api:0.5
curl -s localhost:8091/version
docker rm -f notes-ghaExpected (with pull and container ID in between):
0.5.1
notes-gha
Save your progress? Sign up for free
Checkpoint
gh release list -R <du>/notes-actionsExpected:
TITLE TYPE TAG NAME PUBLISHED
v0.5.1 Latest v0.5.1 about 2 minutes ago
v0.5.0 v0.5.0 about 4 minutes ago
gh release view v0.5.1 -R <du>/notes-actions --json assets --jq '.assets[].name'Expected:
notes-api-linux-amd64
notes-api-linux-arm64
SHA256SUMS
Challenge
Tags with a hyphen such as v0.6.0-rc.1 are pre-releases.
Make sure they show up as Pre-release and not as
“Latest”.
Hint: gh release create --prerelease. A
step with if: and
contains(github.ref_name, '-') – or two steps.
Solution
Only the release job changes – the whole file:
cat > .github/workflows/release.yml <<'EOF'
name: release
on:
push:
tags: ['v*']
permissions:
contents: write
jobs:
build:
strategy:
matrix:
goarch: [amd64, arm64]
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v7
- uses: actions/setup-go@v7
with:
go-version-file: go.mod
- name: Bauen
env:
CGO_ENABLED: "0"
GOOS: linux
GOARCH: ${{ matrix.goarch }}
run: >-
go build -trimpath -ldflags "-s -w -X main.version=${GITHUB_REF_NAME#v}"
-o notes-api-linux-$GOARCH .
- uses: actions/upload-artifact@v7
with:
name: notes-api-linux-${{ matrix.goarch }}
path: notes-api-linux-${{ matrix.goarch }}
release:
needs: build
runs-on: ubuntu-24.04
steps:
- uses: actions/download-artifact@v8
with:
pattern: notes-api-linux-*
merge-multiple: true
- name: Prüfsummen
run: sha256sum notes-api-linux-* > SHA256SUMS
- name: Release anlegen
env:
GH_TOKEN: ${{ github.token }}
VORAB: ${{ contains(github.ref_name, '-') }}
run: >-
gh release create "$GITHUB_REF_NAME" notes-api-linux-* SHA256SUMS
--repo "$GITHUB_REPOSITORY" --generate-notes --prerelease="$VORAB"
EOF
git commit -qam "release: Vorabversionen"
git push -q
git tag v0.6.0-rc.1
git push -q origin v0.6.0-rc.1As soon as the run is finished:
gh release list -R <du>/notes-actionsExpected:
TITLE TYPE TAG NAME PUBLISHED
v0.6.0-rc.1 Pre-release v0.6.0-rc.1 less than a minute ago
v0.5.1 Latest v0.5.1 about 4 minutes ago
v0.5.0 v0.5.0 about 6 minutes ago
contains() returns true or
false, and --prerelease=false is a valid value
for gh. One step is enough.
metadata-action recognizes pre-releases too: the image
gets the tag 0.6.0-rc.1, but neither 0.6 nor
latest.
Save your progress? Sign up for free
Enterprise Note
- Protect tags: A ruleset with
target: tagdefines who may create or deletev*. Otherwise anyone with write access can trigger a release – or move a published tag to a different commit. - Immutable releases: GitHub can lock releases after publishing (Settings → Releases → Immutable releases). Assets and tag can then no longer be swapped.
- Version numbers automatically: Tools such as release-please or semantic-release read Conventional Commits and propose the next version including a changelog as a pull request. The merge sets the tag – and triggers this workflow.
- GoReleaser handles building, checksums, release and images for Go projects in one tool – worthwhile as soon as more platforms come into play.