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ßenghcr.io/<besitzer>/<name>:<tag>– alles in Kleinbuchstaben. - Im Workflow meldet sich
docker/login-actionmit demGITHUB_TOKENan, einem Token, das GitHub für jeden Lauf neu ausstellt. Ein Passwort brauchst du nicht. docker/metadata-actionleitet Tags und Labels aus Git ab,docker/build-push-actionbaut 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 1setup-buildx-actionrichtet 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 -uErwartet:
#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 -qpermissions:legt fest, was dasGITHUB_TOKENdarf. Neue Repositorys geben ihm nur Leserechte.packages: writeerlaubt den Push in die Registry. Mehr dazu an Tag 9.type=ref,event=branchmacht aus dem Branchmaindas Tagmain,type=shadas Tagsha-plus sieben Zeichen Commit.steps.meta.outputs.labelssetzt OCI-Labels wieorg.opencontainers.image.source. Über dieses Label verknüpft GitHub das Paket mit deinem Repository.VERSIONwirdmain– der erste Tag ausmetadata-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 -uErwartet (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/versionErwartet:
main
Davor meldet Docker den Pull und die ID des neuen Containers.
docker rm -f notes-ghaFortschritt 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 -qcache-to: type=gha,mode=maxspeichert die Schichten aller Stages, nicht nur die des fertigen Images. Erst damit lohnt sich der Cache bei Multi-Stage-Builds.cache-from: type=ghaliest sie beim nächsten Lauf.
Der erste Lauf füllt den Cache. Ein zweiter Lauf mit
workflow_dispatch:
gh workflow run image.ymlMit 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 --fillNach ein paar Sekunden:
gh pr checks --watch | grep imageErwartet (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/nullErwartet:
[]
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: writejedes Paket überschreiben. - Tags sind beweglich:
mainzeigt morgen auf ein anderes Image. Deployments referenzieren das Image über den Digest (@sha256:…) oder ein unveränderliches Tag wiesha-…oder eine Versionsnummer (Tag 7). - Aufräumen: GHCR löscht nichts von selbst.
actions/delete-package-versionsoder 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 isttype=registrymit einem eigenen Cache-Tag oft die bessere Wahl.