Skip to content
Hands-on IT IT Drills

Day 7: Releases

Goal: A Git tag v0.5.0 triggers 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 create creates it – in a workflow too.
  • The push trigger with tags: ['v*'] starts a workflow for every new tag that begins with v. GITHUB_REF_NAME then contains the tag name.
  • For releases, the GITHUB_TOKEN needs contents: write.
  • metadata-action turns v0.5.1 into the image tags 0.5.1 and 0.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.0 becomes 0.5.0.
  • pattern: with merge-multiple: true downloads all matching artifacts into one folder – without merge-multiple, each would get a subfolder of its own.
  • gh is preinstalled on GitHub’s runners. It reads the token from GH_TOKEN. github.token is the same as secrets.GITHUB_TOKEN.
  • --generate-notes writes 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 1

Expected (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.0

Expected (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 SHA256SUMS

Expected:

notes-api-linux-amd64: OK
  • -p selects assets by pattern. Several -p are allowed.
  • --ignore-missing checks 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 %1

Expected (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.1
  • type=semver,pattern={{version}} turns the Git tag v0.5.1 into the image tag 0.5.1. {{major}}.{{minor}} yields 0.5 – a tag that always points to the latest patch of the series.
  • semver only applies to tags. For pushes to main, the line produces nothing.
  • paths-ignore does 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 contains 0.5.1.
  • You did not ask for latest: metadata-action assigns it on its own as soon as a semver tag is created. If you don’t want that, set flavor: 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-gha

Expected (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-actions

Expected:

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

As soon as the run is finished:

gh release list -R <du>/notes-actions

Expected:

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: tag defines who may create or delete v*. 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.