Day 3: Build, Matrix, Cache, Artifacts
Goal: Test notes-api on two architectures, build for both, pass results between jobs as artifacts and download them, and understand what the cache saves. · Duration: approx. 75 min · Prerequisite: Day 2
Briefing
- A matrix multiplies a job: one copy per value, all
in parallel.
${{ matrix.<name> }}substitutes the value. - The cache keeps files between runs, e.g. downloaded
Go modules.
setup-gouses it on its own. - An artifact is the result of a run: files that a job uploads and that a later job or you yourself download.
┌─ test (ubuntu-24.04) ─┐ ┌─ build amd64 ─► artifact ─┐
push ─────┤ ├─needs─►┤ ├─► smoke
└─ test (ubuntu-24.04-arm) ─┘ └─ build arm64 ─► artifact ─┘
Drill 1: A 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.oshas two values, so there are twotestjobs. They run at the same time.ubuntu-24.04-armis a runner with an ARM processor. For public repositories it is free, like the x86 runners.
With the ID, as soon as the run is finished:
gh run view <ID>Expected (shortened):
✓ 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 also contains the command lines. The pattern
matches only lines of the step “Architektur” that end in
amd64 or arm64 – the outputs. Expected
(timestamps shortened):
test (ubuntu-24.04) Architektur 2026-11-03T09:12:54Z amd64
test (ubuntu-24.04-arm) Architektur 2026-11-03T09:12:54Z arm64
If one job of the matrix fails, GitHub cancels the others that are
still running (fail-fast: true is the default). With
fail-fast: false under strategy:, all of them
run to the end – useful when you want to know everywhere it breaks.
Save your progress? Sign up for free
Drill 2: The cache
gh run view <ID> --log | grep -E 'Cache (restored from|is not found)'Expected (key shortened):
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
The x86 job finds the cache from the runs of Days 1 and 2. For ARM
there wasn’t one yet. At the end of the job, setup-go saves
the modules and the build cache:
gh cache listExpected (keys shortened):
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...
- The key contains operating system, architecture, Go version and a
hash over
go.sum. If a dependency changes, a new key is created. - A cache belongs to a branch. Pull requests may read the cache of
main, butmainmay not read that of a pull request. - GitHub keeps 10 GB per repository and deletes entries that nobody has read for a week.
A second run without a code change:
gh run rerun <ID>With the same ID, as soon as the run is finished:
gh run view <ID> --log | grep 'Cache restored from'Expected (shortened):
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: ...
The key of the ARM cache is
setup-go-Linux-arm64-ubuntu24-arm64-go-1.27.0-<Hash über go.sum>.
gh run rerun starts the same run once more – same
commit, same ID, a new attempt (“attempt 2”).
Save your progress? Sign up for free
Drill 3: Building and artifacts
A second job builds the binary for both architectures – on a single x86 runner, because Go can cross-compile:
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: >-folds the two lines into one command – long commands stay readable.-X main.version=…sets the variableversioninmain.goat build time. The binary later reports the commit it comes from.retention-days: 7: Without it, GitHub keeps artifacts for 90 days.
With the ID, as soon as the run is finished:
gh run view <ID>Expected (shortened):
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
Download and start it on the VM:
cd ~/gha-lab
gh run download <ID> -R <du>/notes-actions -n notes-api-linux-amd64 -D bin
ls -l binExpected (shortened):
total 11448
-rwxr-xr-x 1 ubuntu ubuntu 11718816 Nov 3 09:16 notes-api-linux-amd64
-nselects an artifact,-Dthe target directory.-Rnames the repository because you are no longer in its folder.xin-rwxr-xr-x:gh run downloadhas kept the execute permission. Thedownload-artifactaction in a job does not – more on that in a moment.
NOTES_API_KEY=lab-api-key-123 PORT=8090 bin/notes-api-linux-amd64 &
curl -s localhost:8090/versionWithout NOTES_API_KEY, notes-api does not start and
reports NOTES_API_KEY oder NOTES_API_KEY_FILE fehlt.
PORT=8090 because on some lab VMs something is already
listening on 8080.
Expected (your commit differs):
b130abd
Before that, notes-api writes three log lines, the last one with
listening addr=:8090.
kill %1
cd ~/gha-lab/notes-actionsSave your progress? Sign up for free
Drill 4: Artifacts between jobs
A third job fetches the amd64 binary and checks whether it starts:
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 >>appends. The indentationsmoke:makes the job a sibling oftestandbuild.- The
smokejob has nocheckout: it needs no source code, only the artifact. chmod +xis necessary here:download-artifactstores the file without execute permission. Without that line the step fails withPermission denied.curl -fexits with an error if the response is not 2xx – the step turns red.
With the ID from gh run list --limit 1, as soon as the
run is finished:
gh run view <ID> --log | grep -E 'smoke.*Z ok$'Expected (timestamp shortened):
smoke Starten und prüfen 2026-11-03T09:29:17Z ok
Save your progress? Sign up for free
Checkpoint
gh run view <ID> --json jobs --jq '.jobs[].name'Expected:
test (ubuntu-24.04)
test (ubuntu-24.04-arm)
build (arm64)
build (amd64)
smoke
The order within a matrix may differ on your machine.
gh api repos/{owner}/{repo}/actions/runs/<ID>/artifacts --jq '.artifacts[].name'Expected:
notes-api-linux-arm64
notes-api-linux-amd64
gh api calls GitHub’s REST API. gh fills in
{owner}/{repo} from the repository in the current
folder.
Challenge
Two quick pushes in a row start two runs, even though only the last one counts. Make sure that a new run on the same branch cancels the old one. Check it with two commits right after each other.
Hint: concurrency: at the top level,
with group: and cancel-in-progress:. For the
second commit, a new file VERSION with 0.5.0
is enough.
Solution
The whole file with the new block at the top:
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 -qAfter about a minute:
gh run list --limit 2 --json displayTitle,conclusion --jq '.[]'Expected:
{"conclusion":"success","displayTitle":"VERSION 0.5.0"}
{"conclusion":"cancelled","displayTitle":"ci: alte Läufe abbrechen"}
- Runs with the same
groupnever run at the same time.cancel-in-progress: truecancels the older one instead of letting it wait. github.refmakes the group per branch: a pull request does not cancel a run onmain.- An empty commit (
git commit --allow-empty) would not have shown anything here: it changes no file, and withpaths-ignoreGitHub then starts no run at all.
Save your progress? Sign up for free
Enterprise Note
- Caches are not storage for results. A cache may be missing without the run failing. Whatever a later job reliably needs belongs in an artifact.
- Artifacts cost storage – for private repositories
counted against the quota. Keep
retention-dayssmall, upload large build outputs only when needed. - Matrix with a sense of proportion: Every
combination costs runner minutes. Many teams test one combination in the
pull request and the full matrix only on
mainor at night.