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-gonutzt 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 1matrix.oshat zwei Werte, also gibt es zwei Jobstest. Sie laufen gleichzeitig.ubuntu-24.04-armist 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 listErwartet (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
mainlesen,mainaber 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 1run: >-faltet die zwei Zeilen zu einem Befehl – lange Befehle bleiben lesbar.-X main.version=…setzt beim Bauen die Variableversioninmain.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 binErwartet (gekürzt):
total 11448
-rwxr-xr-x 1 ubuntu ubuntu 11718816 Nov 3 09:16 notes-api-linux-amd64
-nwählt ein Artefakt,-Ddas Zielverzeichnis.-Rnennt das Repository, weil du nicht mehr in seinem Ordner stehst.xin-rwxr-xr-x:gh run downloadhat das Ausführungsrecht übernommen. Die Actiondownload-artifactin 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/versionOhne 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-actionsFortschritt 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 -qcat >>hängt an. Die Einrückungsmoke:macht den Job zum Geschwister vontestundbuild.- Der Job
smokehat keincheckout: Er braucht keinen Quellcode, nur das Artefakt. chmod +xist hier nötig:download-artifactlegt die Datei ohne Ausführungsrecht ab. Ohne die Zeile scheitert der Step mitPermission denied.curl -fendet 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
EOFgit 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 -qNach 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
grouplaufen nie gleichzeitig.cancel-in-progress: truebricht den älteren ab, statt ihn warten zu lassen. github.refmacht die Gruppe pro Branch: Ein Pull-Request bricht keinen Lauf aufmainab.- Ein leerer Commit (
git commit --allow-empty) hätte hier nichts gezeigt: Er ändert keine Datei, und mitpaths-ignorestartet 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-daysklein 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
mainoder nachts.