Docker Build GitHub Actions Workflow Vorlage
Zuletzt aktualisiert am
Dies ist eine funktionierende .github/workflows/ci.yml, die Ihr Docker-Image bei jedem Pull Request baut und von main aus in die GitHub Container Registry (GHCR) pusht. Sie verwendet Buildx mit dem Layer-Cache von GitHub Actions, sodass unveränderte Layer nicht neu gebaut werden.
Der Workflow
name: CI
on:
push:
branches: [main]
pull_request:
permissions:
contents: read
concurrency:
group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
env:
IMAGE: ghcr.io/${{ github.repository }}
jobs:
build:
runs-on: ubuntu-latest
timeout-minutes: 30
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
- uses: docker/setup-buildx-action@v3
- uses: docker/login-action@v3
if: github.event_name != 'pull_request'
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- id: meta
uses: docker/metadata-action@v5
with:
images: ${{ env.IMAGE }}
tags: |
type=sha
type=raw,value=latest,enable={{is_default_branch}}
- uses: docker/build-push-action@v6
with:
context: .
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=gha
cache-to: type=gha,mode=max
Was die nicht offensichtlichen Teile bewirken
- Berechtigungen. Der Standard des Workflows ist schreibgeschützt. Der Job ergänzt
packages: write, weil nur er Images pusht. Pull Requests aus Forks erhalten ohnehin ein schreibgeschütztes Token und können daher nicht pushen. setup-buildx-actionerstellt einen Buildx-Builder. Der Standard-Docker-Treiber kann den GitHub-Cache nicht exportieren, daher ist dieser Schritt fürcache-to: type=ghaerforderlich.- Anmeldung nur beim Pushen. Bei Pull Requests gibt es nichts zu pushen, daher wird dieser Schritt übersprungen.
docker/metadata-actionerzeugt Tags und OCI-Labels. Das Beispiel versieht jeden Build mit dem Commit-SHA und ergänzt auf dem Standardbranchlatest.- Ausdruck
push:. Pull Requests werden nur gebaut, als Prüfung, dass das Dockerfile noch funktioniert. Pushes aufmainbauen und pushen. cache-fromundcache-to: type=gha,mode=maxlesen und schreiben den Cache von GitHub Actions.mode=maxcached jeden Layer jeder Stufe, was bei Multi-Stage-Builds wichtig ist, belegt aber mehr Cache-Speicher. Siehe Cache-Limits.- Die Reihenfolge im Dockerfile ist wichtiger als jede Einstellung. Kopieren Sie Lockfiles und installieren Sie Abhängigkeiten, bevor Sie den Quellcode kopieren, damit Codeänderungen die Abhängigkeits-Layer nicht ungültig machen. Die vollständige Liste der Techniken finden Sie unter Docker-Layer-Caching in CI.
Varianten
Multi-Plattform-Images
Fügen Sie docker/setup-qemu-action@v3 vor Buildx und platforms: linux/amd64,linux/arm64 im Build-Schritt hinzu. Emulierte arm64-Builds sind langsam; verwenden Sie einen nativen ARM-Runner, wenn es auf Geschwindigkeit ankommt.
Vor dem Push scannen
Fügen Sie vor dem Push einen Schritt zur Schwachstellenprüfung des gebauten Images hinzu und lassen Sie den Lauf bei Befunden mit hohem Schweregrad fehlschlagen.
Tests im Image ausführen
Fügen Sie einen ersten Build-Schritt mit load: true, push: false und einer Test-Stufe hinzu und führen Sie danach docker run auf dem Ergebnis aus. Die Layer werden über denselben Cache geteilt.
Docker Hub oder ECR
Ändern Sie registry, den Anmeldeschritt und images. Für AWS verwenden Sie OIDC mit aws-actions/amazon-ecr-login@v2 statt gespeicherter Schlüssel.
Deploy-Job
Fügen Sie einen zweiten Job mit needs: build hinzu, der den gepushten SHA-Tag deployt.
macOS
Docker ist auf macOS-Runnern nicht verfügbar. Führen Sie Container-Builds auf Linux aus.
Auf schnelleren Maschinen ausführen
Docker-Builds sind CPU- und speicherintensiv, und Layer-Caches helfen nur, wenn sie nah am Build liegen. Ändern Sie eine Zeile:
runs-on: [self-hosted, Linux, compiler-ci]
Der Job läuft auf einer frischen 8-vCPU-Maschine von compiler.dev, die einen Docker-Layer-Cache auf dem Rechner vorhält, mit automatischem Fallback auf Ihren ursprünglichen Runner. Für Image-Builds können speziell dedizierte Builder wie Depot schneller sein; vergleichen Sie die Optionen unter schnellere GitHub Actions Runner. Die Preise finden Sie unter Preise.
FAQ
Warum nutzt mein Build den Cache nicht?
Prüfen Sie, ob Buildx eingerichtet ist, ob cache-from und cache-to übereinstimmen und ob ein früher Dockerfile-Layer nicht bei jedem Lauf wechselt (etwa weil zuerst das gesamte Repository kopiert wird).
Ist der GitHub-Cache groß genug?
Repositories haben eine Größenbegrenzung, die sich alle Caches teilen, und alte Einträge werden entfernt. Große Images können sie füllen.
Pushen Pull Requests aus Forks Images?
Nein. Der Ausdruck push ist für Pull Requests false, und Fork-Tokens sind schreibgeschützt.
Wofür sind dann Artefakte da?
Verwenden Sie ein Artefakt, um ein gebautes Tarball zwischen Jobs weiterzugeben, nicht zum Layer-Caching.
Verwandt
- Docker-Build in der CI langsam? Ursache finden und behebenDocker-Build in CI zu langsam? Build-Kontext, .dockerignore, Layer-Reihenfolge, Cache-Misses und BuildKit prüfen und zuerst das größte Problem beheben.
- Docker-Layer-Caching in der CI mit BuildxDocker-Builds in GitHub Actions beschleunigen: buildx cache-from und cache-to, gha- und registry-Backends und ein Dockerfile für Cache-Treffer.
- Docker Pull Rate Limit in GitHub Actions: Lösungen"toomanyrequests: You have reached your pull rate limit" in GitHub Actions beheben: Docker-Hub-Limits, docker/login-action, Mirrors und GHCR-Alternativen.
- .NET GitHub Actions Workflow-VorlageFertige GitHub-Actions-CI für .NET mit NuGet-Cache, Restore-, Build- und Test-Schritten, optionalem SQL-Server-Dienst, Concurrency und Berechtigungen.