Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 6: Images bauen und nach GHCR pushen

Ziel: Mit Buildx ein Image von notes-api für amd64 und arm64 bauen, mit sinnvollen Tags in die GitHub Container Registry schieben, den Build-Cache von GitHub nutzen und das Image auf der VM starten. · Dauer: ca. 75 min · Voraussetzung: Tag 5

Briefing

  • GHCR (ghcr.io) ist die Container Registry von GitHub. Images heißen ghcr.io/<besitzer>/<name>:<tag> – alles in Kleinbuchstaben.
  • Im Workflow meldet sich docker/login-action mit dem GITHUB_TOKEN an, einem Token, das GitHub für jeden Lauf neu ausstellt. Ein Passwort brauchst du nicht.
  • docker/metadata-action leitet Tags und Labels aus Git ab, docker/build-push-action baut mit Buildx und schiebt das Ergebnis.
  • Der Dockerfile von notes-api übersetzt Go selbst für die Zielarchitektur (--platform=$BUILDPLATFORM). Darum ist kein QEMU nötig.
 push main ─► image.yml: checkout ─► buildx ─► login ghcr ─► metadata ─► build+push
                                                                         │
                         ghcr.io/<du>/notes-api:main, :sha-1a2b3c4 ◄──────┘
                         (amd64 + arm64, ein Tag für beide)

Drill 1: Bauen ohne Push

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

jobs:
  image:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v7
      - uses: docker/setup-buildx-action@v4
      - uses: docker/build-push-action@v7
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: false
EOF
git add .github
git commit -qm "image: bauen"
git push -q
gh run list --workflow image.yml --limit 1
  • setup-buildx-action richtet einen Buildx-Builder ein, der mehrere Plattformen auf einmal bauen kann.
  • context: . nimmt die Dateien aus dem Checkout. Ohne Angabe baut die Action direkt aus dem Git-Repository und ignoriert lokale Änderungen früherer Steps.
  • push: false: nur bauen. So prüfst du, ob der Dockerfile baut.

Mit der ID, sobald der Lauf fertig ist:

gh run view <ID> --log | grep -oE '#[0-9]+ \[[^]]*build 1/1\]' | sort -u

Erwartet:

#14 [linux/amd64->arm64 build 1/1]
#15 [linux/amd64 build 1/1]

Die Stage build läuft zweimal, einmal pro Zielplattform. linux/amd64->arm64 heißt: gebaut auf amd64, für arm64. grep -o gibt nur den passenden Teil der Zeile aus, sort -u entfernt doppelte Zeilen – Buildx meldet jeden Schritt beim Start und beim Ende.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Push nach GHCR

cat > .github/workflows/image.yml <<'EOF'
name: image
on:
  push:
    branches: [main]
    paths-ignore: ['**.md']
  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
      - 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=sha
      - uses: docker/build-push-action@v7
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          build-args: |
            VERSION=${{ steps.meta.outputs.version }}
            REVISION=${{ github.sha }}
EOF
git commit -qam "image: nach GHCR"
git push -q
  • permissions: legt fest, was das GITHUB_TOKEN darf. Neue Repositorys geben ihm nur Leserechte. packages: write erlaubt den Push in die Registry. Mehr dazu an Tag 9.
  • type=ref,event=branch macht aus dem Branch main das Tag main, type=sha das Tag sha- plus sieben Zeichen Commit.
  • steps.meta.outputs.labels setzt OCI-Labels wie org.opencontainers.image.source. Über dieses Label verknüpft GitHub das Paket mit deinem Repository.
  • VERSION wird main – der erste Tag aus metadata-action. An Tag 7 wird daraus eine echte Versionsnummer.

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

gh run view <ID> --log | grep -oE 'pushing manifest for [^@]+' | sort -u

Erwartet (der Commit weicht ab):

pushing manifest for ghcr.io/<du>/notes-api:main
pushing manifest for ghcr.io/<du>/notes-api:sha-57b78f0

Zwei Tags, ein Image. Das Paket in GitHub:

gh api /user/packages/container/notes-api \
  --jq '.name, .visibility, .repository.full_name'

Erwartet:

notes-api
public
<du>/notes-actions

Das Paket ist öffentlich: Ein Paket, das ein Workflow mit dem GITHUB_TOKEN anlegt, ist mit seinem Repository verknüpft und übernimmt dessen Sichtbarkeit. Pakete aus privaten Repositorys bleiben privat.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Das Image auf der VM

Ein öffentliches Image holt Docker ohne Anmeldung:

docker buildx imagetools inspect ghcr.io/<du>/notes-api:main | grep -E 'Platform'

Erwartet:

  Platform:    linux/amd64
  Platform:    linux/arm64
  Platform:    unknown/unknown
  Platform:    unknown/unknown

Ein Tag, zwei Images. Die beiden unknown/unknown sind die Attestationen, die Buildx von sich aus anhängt (Provenance – mehr an Tag 8).

docker run -d --name notes-gha -p 8091:8080 -e NOTES_API_KEY=lab-api-key-123 \
  ghcr.io/<du>/notes-api:main
curl -s localhost:8091/version

Erwartet:

main

Davor meldet Docker den Pull und die ID des neuen Containers.

docker rm -f notes-gha

Fortschritt speichern? Kostenlos registrieren

Drill 4: Der Build-Cache

Jeder Lauf baut bisher von vorn: go mod download und go build für zwei Plattformen. Buildx kann seinen Cache im Cache von GitHub Actions ablegen. In image.yml kommen zwei Zeilen zur letzten Action dazu:

cat > .github/workflows/image.yml <<'EOF'
name: image
on:
  push:
    branches: [main]
    paths-ignore: ['**.md']
  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
      - 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=sha
      - uses: docker/build-push-action@v7
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          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: Build-Cache"
git push -q
  • cache-to: type=gha,mode=max speichert die Schichten aller Stages, nicht nur die des fertigen Images. Erst damit lohnt sich der Cache bei Multi-Stage-Builds.
  • cache-from: type=gha liest sie beim nächsten Lauf.

Der erste Lauf füllt den Cache. Ein zweiter Lauf mit workflow_dispatch:

gh workflow run image.yml

Mit der ID, sobald der Lauf fertig ist:

gh run view <ID> --log | grep -c ' CACHED$'

Erwartet (die Zahl kann abweichen):

8
gh run list --workflow image.yml --limit 2 --json event,startedAt,updatedAt \
  --jq '.[] | .event + " " + .startedAt + " " + .updatedAt'

Erwartet (Zeiten weichen ab):

workflow_dispatch 2026-11-03T10:18:32Z 2026-11-03T10:19:04Z
push 2026-11-03T10:15:52Z 2026-11-03T10:17:00Z

Start und Ende jedes Laufs: Der Lauf aus dem Cache braucht 32 Sekunden statt 68.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

docker buildx imagetools inspect ghcr.io/<du>/notes-api:main \
  --format '{{json .Manifest.MediaType}}'

Erwartet:

"application/vnd.oci.image.index.v1+json"

Ein Index: eine Liste, die je Plattform auf ein eigenes Image zeigt.

gh api /user/packages/container/notes-api/versions --jq '.[0].metadata.container.tags'

Erwartet (der Commit weicht ab):

["sha-631ce39","main"]

Challenge

Auch Pull-Requests sollen das Image bauen – damit ein kaputter Dockerfile vor dem Merge auffällt –, aber nichts in die Registry schieben.

Hinweis: Trigger pull_request, und push: der Build-Action kann ein Ausdruck sein. docker/login-action braucht ein if:.

Lösung

cat > .github/workflows/image.yml <<'EOF'
name: image
on:
  push:
    branches: [main]
    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=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 switch -c image-pr
git commit -qam "image: auch in Pull-Requests bauen"
git push -q -u origin image-pr
gh pr create --fill

Nach ein paar Sekunden:

gh pr checks --watch | grep image

Erwartet (die letzte Zeile, gekürzt):

✓  image/image (pull_request)                52s      https://github.com/<du>/...

--watch gibt die Tabelle bei jeder Aktualisierung neu aus; grep zeigt darum mehrere Zeilen, erst mit *, am Ende mit ✓.

gh api /user/packages/container/notes-api/versions \
  --jq '[.[].metadata.container.tags[] | select(startswith("pr-"))]'
gh pr merge --squash --delete-branch >/dev/null

Erwartet:

[]

type=ref,event=pr hätte das Tag pr- plus Nummer des Pull-Requests erzeugt – es steht aber nicht in der Registry, weil push im Pull-Request false ist.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Pakete gehören zur Organisation: In Organisationen legst du fest, welche Repositorys in welches Paket schreiben dürfen (Package settings → Manage Actions access). Sonst kann jedes Repository mit packages: write jedes Paket überschreiben.
  • Tags sind beweglich: main zeigt morgen auf ein anderes Image. Deployments referenzieren das Image über den Digest (@sha256:…) oder ein unveränderliches Tag wie sha-… oder eine Versionsnummer (Tag 7).
  • Aufräumen: GHCR löscht nichts von selbst. actions/delete-package-versions oder eine Richtlinie hält ungetaggte Versionen klein.
  • Cache-Grenzen: Der gha-Cache teilt sich die 10 GB pro Repository mit allen anderen Caches. Für große Images ist type=registry mit einem eigenen Cache-Tag oft die bessere Wahl.