Skip to content
Hands-on IT IT Drills

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-go uses 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 1
  • matrix.os has two values, so there are two test jobs. They run at the same time.
  • ubuntu-24.04-arm is 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 list

Expected (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, but main may 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 1
  • run: >- folds the two lines into one command – long commands stay readable.
  • -X main.version=… sets the variable version in main.go at 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 bin

Expected (shortened):

total 11448
-rwxr-xr-x 1 ubuntu ubuntu 11718816 Nov  3 09:16 notes-api-linux-amd64
  • -n selects an artifact, -D the target directory. -R names the repository because you are no longer in its folder.
  • x in -rwxr-xr-x: gh run download has kept the execute permission. The download-artifact action 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/version

Without 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-actions

Save 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 -q
  • cat >> appends. The indentation smoke: makes the job a sibling of test and build.
  • The smoke job has no checkout: it needs no source code, only the artifact.
  • chmod +x is necessary here: download-artifact stores the file without execute permission. Without that line the step fails with Permission denied.
  • curl -f exits 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
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

After 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 group never run at the same time. cancel-in-progress: true cancels the older one instead of letting it wait.
  • github.ref makes the group per branch: a pull request does not cancel a run on main.
  • An empty commit (git commit --allow-empty) would not have shown anything here: it changes no file, and with paths-ignore GitHub 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-days small, 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 main or at night.