Zum Inhalt springen

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-action erstellt einen Buildx-Builder. Der Standard-Docker-Treiber kann den GitHub-Cache nicht exportieren, daher ist dieser Schritt für cache-to: type=gha erforderlich.
  • Anmeldung nur beim Pushen. Bei Pull Requests gibt es nichts zu pushen, daher wird dieser Schritt übersprungen.
  • docker/metadata-action erzeugt Tags und OCI-Labels. Das Beispiel versieht jeden Build mit dem Commit-SHA und ergänzt auf dem Standardbranch latest.
  • Ausdruck push:. Pull Requests werden nur gebaut, als Prüfung, dass das Dockerfile noch funktioniert. Pushes auf main bauen und pushen.
  • cache-from und cache-to: type=gha,mode=max lesen und schreiben den Cache von GitHub Actions. mode=max cached 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.