Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 7: Releases

Ziel: Ein Git-Tag v0.5.0 löst ein GitHub-Release mit Binärdateien, Prüfsummen und Release Notes aus – und ein Image mit Versionsnummer. · Dauer: ca. 60 min · Voraussetzung: Tag 6

Briefing

  • Ein Release auf GitHub hängt an einem Git-Tag: Titel, Text, angehängte Dateien („Assets“). gh release create legt es an – auch im Workflow.
  • Der Trigger push mit tags: ['v*'] startet einen Workflow für jedes neue Tag, das mit v beginnt. GITHUB_REF_NAME enthält dann den Tag-Namen.
  • Für Releases braucht das GITHUB_TOKEN contents: write.
  • metadata-action macht aus v0.5.1 die Image-Tags 0.5.1 und 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: Der 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} ist Bash: Aus v0.5.0 wird 0.5.0.
  • pattern: mit merge-multiple: true lädt alle passenden Artefakte in einen Ordner – ohne merge-multiple bekäme jedes einen eigenen Unterordner.
  • gh ist auf den Runnern von GitHub vorinstalliert. Es liest den Token aus GH_TOKEN. github.token ist dasselbe wie secrets.GITHUB_TOKEN.
  • --generate-notes schreibt die Release Notes aus den Pull-Requests seit dem letzten Release.

Das Tag setzen und pushen:

git tag v0.5.0
git push -q origin v0.5.0
gh run list --workflow release.yml --limit 1

Erwartet (nach ein paar Sekunden):

STATUS  TITLE                      WORKFLOW  BRANCH  EVENT  ID           ELAPSED  AGE
*       release: Workflow für Tags release   v0.5.0  push   41618966812  17s      now

Als BRANCH steht der Tag-Name, als Titel die Nachricht des getaggten Commits.

Sobald der Lauf fertig ist:

gh release view v0.5.0

Erwartet (gekürzt):

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

Veröffentlicht hat github-actions[bot] – das Konto hinter dem GITHUB_TOKEN.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Herunterladen und prüfen

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

Erwartet:

notes-api-linux-amd64: OK
  • -p wählt Assets nach Muster. Mehrere -p sind erlaubt.
  • --ignore-missing prüft nur die Dateien, die da sind – die arm64-Datei hast du nicht geladen.

Die Version steckt in der Binärdatei:

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

Erwartet (dazwischen Logzeilen von notes-api):

0.5.0

chmod +x, weil Release-Assets – anders als Artefakte mit gh run download – ohne Ausführungsrecht ankommen.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Images mit Versionsnummer

image.yml soll auch bei Tags laufen und Versions-Tags vergeben. Die neue Datei (geändert: tags: unter push, zwei type=semver-Zeilen):

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}} macht aus dem Git-Tag v0.5.1 das Image-Tag 0.5.1. {{major}}.{{minor}} ergibt 0.5 – ein Tag, das immer auf den neuesten Patch der Reihe zeigt.
  • semver greift nur bei Tags. Bei Pushes auf main erzeugt die Zeile nichts.
  • paths-ignore gilt nicht für Tags – ein Tag-Push startet den Workflow immer.

Sobald der Lauf aus gh run list --workflow image.yml --limit 1 fertig ist:

gh api /user/packages/container/notes-api/versions \
  --jq '.[].metadata.container.tags | select(index("0.5.1"))'

Erwartet:

["latest","0.5","0.5.1"]
  • select(index("0.5.1")) behält nur die Version, deren Tag-Liste 0.5.1 enthält.
  • latest hast du nicht bestellt: metadata-action vergibt es von sich aus, sobald ein semver-Tag entsteht. Wer das nicht will, setzt 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

Erwartet (dazwischen Pull und Container-ID):

0.5.1
notes-gha

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

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

Erwartet:

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'

Erwartet:

notes-api-linux-amd64
notes-api-linux-arm64
SHA256SUMS

Challenge

Tags mit Bindestrich wie v0.6.0-rc.1 sind Vorabversionen. Sorge dafür, dass sie als Pre-release erscheinen und nicht als „Latest“.

Hinweis: gh release create --prerelease. Ein Step mit if: und contains(github.ref_name, '-') – oder zwei Steps.

Lösung

Nur der Job release ändert sich – die ganze Datei:

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

Sobald der Lauf fertig ist:

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

Erwartet:

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() liefert true oder false, und --prerelease=false ist für gh ein gültiger Wert. Ein Step genügt.

Auch metadata-action erkennt Vorabversionen: Das Image bekommt das Tag 0.6.0-rc.1, aber weder 0.6 noch latest.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Tags schützen: Ein Ruleset mit target: tag legt fest, wer v* anlegen oder löschen darf. Sonst kann jeder mit Schreibrechten ein Release auslösen – oder ein veröffentlichtes Tag auf einen anderen Commit umbiegen.
  • Unveränderliche Releases: GitHub kann Releases nach dem Veröffentlichen sperren (Settings → Releases → Immutable releases). Assets und Tag lassen sich dann nicht mehr austauschen.
  • Versionsnummern automatisch: Werkzeuge wie release-please oder semantic-release lesen Conventional Commits und schlagen die nächste Version samt Changelog als Pull-Request vor. Der Merge setzt das Tag – und löst diesen Workflow aus.
  • GoReleaser erledigt Bauen, Prüfsummen, Release und Images für Go-Projekte in einem Werkzeug – sinnvoll, sobald es mehr Plattformen werden.