Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 3: Bauen, Matrix, Cache, Artefakte

Ziel: notes-api auf zwei Architekturen testen, für beide bauen, Ergebnisse als Artefakte zwischen Jobs weiterreichen und herunterladen, und verstehen, was der Cache spart. · Dauer: ca. 75 min · Voraussetzung: Tag 2

Briefing

  • Eine Matrix vervielfacht einen Job: eine Kopie pro Wert, alle parallel. ${{ matrix.<name> }} setzt den Wert ein.
  • Der Cache hebt Dateien zwischen Läufen auf, z. B. heruntergeladene Go-Module. setup-go nutzt ihn von selbst.
  • Ein Artefakt ist das Ergebnis eines Laufs: Dateien, die ein Job hochlädt und ein späterer Job oder du selbst herunterlädst.
           ┌─ test (ubuntu-24.04)      ─┐        ┌─ build amd64 ─► Artefakt ─┐
 push ─────┤                            ├─needs─►┤                           ├─► smoke
           └─ test (ubuntu-24.04-arm)  ─┘        └─ build arm64 ─► Artefakt ─┘

Drill 1: Eine Matrix

cd ~/gha-lab/notes-actions
cat > .github/workflows/ci.yml <<'EOF'
name: ci
on:
  push:
    branches: [main]
    paths-ignore: ['**.md']
  pull_request:

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-24.04, ubuntu-24.04-arm]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v7
        with:
          go-version-file: go.mod
      - name: Architektur
        run: go env GOARCH
      - name: Statische Prüfung
        run: go vet ./...
      - run: go test ./...
      - name: PR-Info
        if: github.event_name == 'pull_request'
        env:
          VON: ${{ github.head_ref }}
          NACH: ${{ github.base_ref }}
        run: echo "PR $VON -> $NACH" | tee -a "$GITHUB_STEP_SUMMARY"
EOF
git commit -qam "ci: Matrix amd64 und arm64"
git push -q
gh run list --limit 1
  • matrix.os hat zwei Werte, also gibt es zwei Jobs test. Sie laufen gleichzeitig.
  • ubuntu-24.04-arm ist ein Runner mit ARM-Prozessor. Für öffentliche Repositorys ist er wie die x86-Runner kostenlos.

Mit der ID, sobald der Lauf fertig ist:

gh run view <ID>

Erwartet (gekürzt):

✓ main ci · 41609160653
Triggered via push less than a minute ago

JOBS
✓ test (ubuntu-24.04) in 18s (ID 125826402389)
✓ test (ubuntu-24.04-arm) in 31s (ID 125826402983)
gh run view <ID> --log | grep -E 'Architektur.*Z (amd64|arm64)$'

--log enthält auch die Befehlszeilen. Das Muster trifft nur Zeilen des Steps „Architektur“, die auf amd64 oder arm64 enden – die Ausgaben. Erwartet (Zeitstempel gekürzt):

test (ubuntu-24.04) Architektur 2026-11-03T09:12:54Z amd64
test (ubuntu-24.04-arm) Architektur 2026-11-03T09:12:54Z arm64

Scheitert ein Job der Matrix, bricht GitHub die anderen noch laufenden ab (fail-fast: true ist die Vorgabe). Mit fail-fast: false unter strategy: laufen alle zu Ende – nützlich, wenn du wissen willst, wo überall es kracht.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Der Cache

gh run view <ID> --log | grep -E 'Cache (restored from|is not found)'

Erwartet (Schlüssel gekürzt):

test (ubuntu-24.04) Run actions/setup-go@v7 ... Cache restored from key: setup-go-...
test (ubuntu-24.04-arm) Run actions/setup-go@v7 ... Cache is not found

Der x86-Job findet den Cache aus den Läufen von Tag 1 und 2. Für ARM gab es noch keinen. Am Ende des Jobs speichert setup-go die Module und den Build-Cache:

gh cache list

Erwartet (Schlüssel gekürzt):

Showing 2 of 2 caches in <du>/notes-actions

ID          KEY                  SIZE       CREATED            ACCESSED
9927733851  setup-go-Linux-a...  48.23 MiB  less than a mi...  less than a mi...
9927071900  setup-go-Linux-x...  49.64 MiB  about 15 minut...  less than a mi...
  • Der Schlüssel enthält Betriebssystem, Architektur, Go-Version und einen Hash über go.sum. Ändert sich eine Abhängigkeit, entsteht ein neuer Schlüssel.
  • Ein Cache gehört zu einem Branch. Pull-Requests dürfen den Cache von main lesen, main aber nicht den eines Pull-Requests.
  • GitHub hält pro Repository 10 GB und löscht Einträge, die eine Woche niemand gelesen hat.

Ein zweiter Lauf ohne Codeänderung:

gh run rerun <ID>

Mit derselben ID, sobald der Lauf fertig ist:

gh run view <ID> --log | grep 'Cache restored from'

Erwartet (gekürzt):

test (ubuntu-24.04) Run actions/setup-go@v7 ... Cache restored from key: ...
test (ubuntu-24.04-arm) Run actions/setup-go@v7 ... Cache restored from key: ...

Der Schlüssel des ARM-Caches lautet setup-go-Linux-arm64-ubuntu24-arm64-go-1.27.0-<Hash über go.sum>.

gh run rerun startet denselben Lauf noch einmal – gleicher Commit, gleiche ID, ein neuer Versuch („attempt 2“).

Fortschritt speichern? Kostenlos registrieren

Drill 3: Bauen und Artefakte

Ein zweiter Job baut die Binärdatei für beide Architekturen – auf einem einzigen x86-Runner, denn Go kann über Architekturen hinweg übersetzen:

cat > .github/workflows/ci.yml <<'EOF'
name: ci
on:
  push:
    branches: [main]
    paths-ignore: ['**.md']
  pull_request:

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-24.04, ubuntu-24.04-arm]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v7
        with:
          go-version-file: go.mod
      - name: Statische Prüfung
        run: go vet ./...
      - run: go test ./...
      - name: PR-Info
        if: github.event_name == 'pull_request'
        env:
          VON: ${{ github.head_ref }}
          NACH: ${{ github.base_ref }}
        run: echo "PR $VON -> $NACH" | tee -a "$GITHUB_STEP_SUMMARY"

  build:
    needs: test
    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_SHA::7}"
          -o notes-api-linux-$GOARCH .
      - uses: actions/upload-artifact@v7
        with:
          name: notes-api-linux-${{ matrix.goarch }}
          path: notes-api-linux-${{ matrix.goarch }}
          retention-days: 7
EOF
git commit -qam "ci: bauen für amd64 und arm64"
git push -q
gh run list --limit 1
  • run: >- faltet die zwei Zeilen zu einem Befehl – lange Befehle bleiben lesbar.
  • -X main.version=… setzt beim Bauen die Variable version in main.go. Die Binärdatei meldet später den Commit, aus dem sie stammt.
  • retention-days: 7: Ohne Angabe hebt GitHub Artefakte 90 Tage auf.

Mit der ID, sobald der Lauf fertig ist:

gh run view <ID>

Erwartet (gekürzt):

JOBS
✓ test (ubuntu-24.04-arm) in 15s (ID 125827352594)
✓ test (ubuntu-24.04) in 22s (ID 125827352704)
✓ build (arm64) in 29s (ID 125827554410)
✓ build (amd64) in 34s (ID 125827554429)

ARTIFACTS
notes-api-linux-arm64
notes-api-linux-amd64

Herunterladen und auf der VM starten:

cd ~/gha-lab
gh run download <ID> -R <du>/notes-actions -n notes-api-linux-amd64 -D bin
ls -l bin

Erwartet (gekürzt):

total 11448
-rwxr-xr-x 1 ubuntu ubuntu 11718816 Nov  3 09:16 notes-api-linux-amd64
  • -n wählt ein Artefakt, -D das Zielverzeichnis. -R nennt das Repository, weil du nicht mehr in seinem Ordner stehst.
  • x in -rwxr-xr-x: gh run download hat das Ausführungsrecht übernommen. Die Action download-artifact in einem Job tut das nicht – dazu gleich mehr.
NOTES_API_KEY=lab-api-key-123 PORT=8090 bin/notes-api-linux-amd64 &
curl -s localhost:8090/version

Ohne NOTES_API_KEY startet notes-api nicht und meldet NOTES_API_KEY oder NOTES_API_KEY_FILE fehlt. PORT=8090, weil auf 8080 auf manchen Lab-VMs schon etwas lauscht.

Erwartet (dein Commit weicht ab):

b130abd

Davor schreibt notes-api drei Logzeilen, die letzte mit listening addr=:8090.

kill %1
cd ~/gha-lab/notes-actions

Fortschritt speichern? Kostenlos registrieren

Drill 4: Artefakte zwischen Jobs

Ein dritter Job holt die amd64-Binärdatei und prüft, ob sie startet:

cat >> .github/workflows/ci.yml <<'EOF'

  smoke:
    needs: build
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/download-artifact@v8
        with:
          name: notes-api-linux-amd64
      - name: Starten und prüfen
        run: |
          chmod +x notes-api-linux-amd64
          NOTES_API_KEY=lab-api-key-123 PORT=8090 ./notes-api-linux-amd64 &
          sleep 1
          curl -fsS localhost:8090/healthz
EOF
git commit -qam "ci: Smoke-Test"
git push -q
  • cat >> hängt an. Die Einrückung smoke: macht den Job zum Geschwister von test und build.
  • Der Job smoke hat kein checkout: Er braucht keinen Quellcode, nur das Artefakt.
  • chmod +x ist hier nötig: download-artifact legt die Datei ohne Ausführungsrecht ab. Ohne die Zeile scheitert der Step mit Permission denied.
  • curl -f endet mit Fehler, wenn die Antwort kein 2xx ist – der Step wird rot.

Mit der ID aus gh run list --limit 1, sobald der Lauf fertig ist:

gh run view <ID> --log | grep -E 'smoke.*Z ok$'

Erwartet (Zeitstempel gekürzt):

smoke   Starten und prüfen  2026-11-03T09:29:17Z ok

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

gh run view <ID> --json jobs --jq '.jobs[].name'

Erwartet:

test (ubuntu-24.04)
test (ubuntu-24.04-arm)
build (arm64)
build (amd64)
smoke

Die Reihenfolge innerhalb einer Matrix kann bei dir anders sein.

gh api repos/{owner}/{repo}/actions/runs/<ID>/artifacts --jq '.artifacts[].name'

Erwartet:

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

gh api ruft die REST-API von GitHub auf. {owner}/{repo} füllt gh aus dem Repository im aktuellen Ordner.

Challenge

Zwei schnelle Pushes hintereinander starten zwei Läufe, obwohl nur der letzte zählt. Sorge dafür, dass ein neuer Lauf auf demselben Branch den alten abbricht. Prüfe es mit zwei Commits direkt nacheinander.

Hinweis: concurrency: auf oberster Ebene, mit group: und cancel-in-progress:. Für den zweiten Commit genügt eine neue Datei VERSION mit 0.5.0.

Lösung

Die ganze Datei mit dem neuen Block oben:

cat > .github/workflows/ci.yml <<'EOF'
name: ci
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

on:
  push:
    branches: [main]
    paths-ignore: ['**.md']
  pull_request:

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-24.04, ubuntu-24.04-arm]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v7
        with:
          go-version-file: go.mod
      - name: Statische Prüfung
        run: go vet ./...
      - run: go test ./...
      - name: PR-Info
        if: github.event_name == 'pull_request'
        env:
          VON: ${{ github.head_ref }}
          NACH: ${{ github.base_ref }}
        run: echo "PR $VON -> $NACH" | tee -a "$GITHUB_STEP_SUMMARY"

  build:
    needs: test
    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_SHA::7}"
          -o notes-api-linux-$GOARCH .
      - uses: actions/upload-artifact@v7
        with:
          name: notes-api-linux-${{ matrix.goarch }}
          path: notes-api-linux-${{ matrix.goarch }}
          retention-days: 7

  smoke:
    needs: build
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/download-artifact@v8
        with:
          name: notes-api-linux-amd64
      - name: Starten und prüfen
        run: |
          chmod +x notes-api-linux-amd64
          NOTES_API_KEY=lab-api-key-123 PORT=8090 ./notes-api-linux-amd64 &
          sleep 1
          curl -fsS localhost:8090/healthz
EOF
git commit -qam "ci: alte Läufe abbrechen"
git push -q
echo 0.5.0 > VERSION
git add VERSION
git commit -qm "VERSION 0.5.0"
git push -q

Nach etwa einer Minute:

gh run list --limit 2 --json displayTitle,conclusion --jq '.[]'

Erwartet:

{"conclusion":"success","displayTitle":"VERSION 0.5.0"}
{"conclusion":"cancelled","displayTitle":"ci: alte Läufe abbrechen"}
  • Läufe mit derselben group laufen nie gleichzeitig. cancel-in-progress: true bricht den älteren ab, statt ihn warten zu lassen.
  • github.ref macht die Gruppe pro Branch: Ein Pull-Request bricht keinen Lauf auf main ab.
  • Ein leerer Commit (git commit --allow-empty) hätte hier nichts gezeigt: Er ändert keine Datei, und mit paths-ignore startet GitHub dann gar keinen Lauf.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Caches sind kein Speicher für Ergebnisse. Ein Cache darf fehlen, ohne dass der Lauf scheitert. Was ein späterer Job sicher braucht, gehört in ein Artefakt.
  • Artefakte kosten Speicher – bei privaten Repositorys auf das Kontingent angerechnet. retention-days klein halten, große Build-Ausgaben nur bei Bedarf hochladen.
  • Matrix mit Augenmaß: Jede Kombination kostet Runner-Minuten. Viele Teams testen im Pull-Request eine Kombination und die volle Matrix erst auf main oder nachts.