Veröffentlichen von Docker-Images

In diesem Lernprogramm erfahren Sie, wie Sie Docker-Images in einer Registrierung veröffentlichen, z. B. Docker Hub oder GitHub Packages, als Teil Ihres CI-Workflows (Continuous Integration).

In diesem Artikel

Einführung

In diesem Handbuch erfahren Sie, wie Sie einen Workflow erstellen, der einen Docker-Build ausführt, und veröffentlicht dann Docker-Images für Docker Hub oder GitHub Packages. Mit einem einzelnen Workflow kannst Du Images in einer einzigen Registry oder in mehreren Registries veröffentlichen.

Hinweis

Wenn Sie in ein anderes Docker-Registry eines Drittanbieters pushen möchten, kann das Beispiel im Abschnitt Veröffentlichen von Images auf GitHub Packages als gute Vorlage dienen.

Voraussetzungen

Wir empfehlen, dass Du ein grundlegendes Verständnis von Workflowkonfigurations-Optionen hast und darüber, wie Du eine Workflow-Datei erstellst. Weitere Informationen finden Sie unter Schreiben von Workflows.

Vielleicht findest Du es auch hilfreich, ein grundlegendes Verständnis von Folgendem zu haben:

  •         [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions)

  •         [AUTOTITLE](/actions/security-guides/automatic-token-authentication)

  •         [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-container-registry)

Informationen zur Image-Konfiguration

In diesem Handbuch wird davon ausgegangen, dass Sie über eine vollständige Definition für ein Docker-Image verfügen, das in einem GitHub Repository gespeichert ist. Dein Repository muss beispielsweise ein Dockerfile und alle anderen Dateien enthalten, die benötigt werden, um einen Docker-Build zum Erstellen eines Images durchzuführen.

          Du kannst deinem Containerimage mithilfe von vordefinierten Anmerkungsschlüsseln Metadaten hinzufügen, z. B. eine Beschreibung, eine Lizenz und ein Quellrepository. Weitere Informationen finden Sie unter [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-container-registry#labelling-container-images).

In diesem Leitfaden wird die Docker-Aktion build-push-action verwendet, um das Docker-Image zu erstellen und an eine oder mehrere Registrierungen zu pushen. Weitere Informationen findest du unter build-push-action.

Veröffentlichen von Bildern auf Docker Hub

Hinweis

Docker Hub erzwingt in der Regel Grenzwerte für Push- und Pullvorgänge, die sich auf Aufträge auf selbstgehosteten Runnern auswirken. Über GitHub gehostete Runner unterliegen diesen Grenzwerten jedoch basierend auf einer Vereinbarung zwischen GitHub und Docker nicht.

Jedes Mal, wenn Sie ein neues Release auf GitHub erstellen, können Sie einen Workflow auslösen, um Ihr Bild zu veröffentlichen. Der Workflow im folgenden Beispiel wird ausgeführt, wenn das release-Ereignis mit dem published-Aktivitätstyp ausgelöst wird.

Im folgenden Beispielworkflow verwenden wir die Docker login-action und build-push-action Aktionen, um das Docker-Image zu erstellen. Wenn der Build erfolgreich ist, übertragen Sie das integrierte Image auf Docker Hub.

Um auf Docker Hub zu übertragen, müssen Sie über ein Docker Hub Konto verfügen und ein Docker Hub Repository erstellt haben. Weitere Informationen finden Sie unter Hochladen eines Docker-Container-Images zu Docker Hub in der Docker-Dokumentation.

Die login-action optionen, die für Docker Hub erforderlich sind: * username und password: Dies ist Ihr Docker Hub Benutzername und Kennwort. Es wird empfohlen, Ihren Docker Hub Benutzernamen und Ihr Kennwort als geheime Schlüssel zu speichern, damit sie in Ihrer Workflowdatei nicht verfügbar gemacht werden. Weitere Informationen finden Sie unter Verwenden von Geheimnissen in GitHub-Aktionen.

Die für Docker Hub erforderliche Option ist: metadata-action * images: Der Namespace und der Name für das Docker-Image, das Sie erstellen/an Docker Hub übertragen.

Die build-push-action optionen, die für Docker Hub erforderlich sind: * tags: Dies ist das Tag deines neuen Images im Format DOCKER-HUB-NAMESPACE/DOCKER-HUB-REPOSITORY:VERSION. Du kannst wie im Folgenden gezeigt ein einzelnes Tag festlegen oder mehrere Tags in einer Liste angeben. * push: Wenn diese Option auf true festgelegt ist, wird das Image bei erfolgreicher Erstellung an die Registry gepusht.

YAML
# Dieser Workflow verwendet Aktionen, die nicht von GitHub zertifiziert sind.
# Sie werden von einem Drittanbieter bereitgestellt und unterliegen
# separaten Nutzungsbedingungen, Datenschutzbestimmungen und Support
# Onlinedokumentation.

# GitHub empfiehlt, Aktionen an einen Commit-SHA anzuheften.
# Um eine neuere Version zu erhalten, musst du den SHA aktualisieren.
# Du kannst auch auf ein Tag oder einen Branch verweisen, aber die Aktion kann sich ohne Vorwarnung ändern.

name: Publish Docker image

on:
  release:
    types: [published]

jobs:
  push_to_registry:
    name: Push Docker image to Docker Hub
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read
      attestations: write
      id-token: write
    steps:
      - name: Check out the repo
        uses: actions/checkout@v5

      - name: Log in to Docker Hub
        uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
        with:
          images: my-docker-hub-namespace/my-docker-hub-repository

      - name: Build and push Docker image
        id: push
        uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671
        with:
          context: .
          file: ./Dockerfile
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

      - name: Generate artifact attestation
        uses: actions/attest@v4
        with:
          subject-name: index.docker.io/my-docker-hub-namespace/my-docker-hub-repository
          subject-digest: ${{ steps.push.outputs.digest }}
          push-to-registry: true

Der oben genannte Workflow checkt das Repository GitHub aus, verwendet die login-action, um sich bei der Registrierung anzumelden, und verwendet dann die Aktion build-push-action, um ein Docker-Image basierend auf dem Dockerfile Ihres Repositorys zu erstellen; Drücken Sie das Bild auf Docker Hub, und wenden Sie ein Tag auf das Bild an.

Im letzten Schritt generiert es einen Artefaktnachweis für das Bild, wodurch die Lieferkettensicherheit erhöht wird. Weitere Informationen finden Sie unter Verwenden von Artefaktnachweisen zur Ermittlung der Herkunft von Builds.

Veröffentlichen von Bildern in GitHub Packages

Jedes Mal, wenn Sie eine neue Version GitHuberstellen, können Sie einen Workflow auslösen, um Ihr Bild zu veröffentlichen. Der Workflow im folgenden Beispiel wird ausgeführt, wenn eine Änderung an die release-Verzweigung gepusht wird.

Im folgenden Beispiel-Workflow verwenden wir Docker-login-action, metadata-action und build-push-action-Aktion, um das Docker-Image zu erstellen, und wenn der Build erfolgreich ist, pushen wir das erstellte Image an GitHub Packages.

Die erforderlichen Optionen für login-action sind GitHub Packages: * registry: Muss auf ghcr.io gesetzt werden. * username: Sie können den Kontext verwenden, um automatisch ${{ github.actor }} den Benutzernamen des Benutzers zu verwenden, der die Workflowausführung ausgelöst hat. Weitere Informationen finden Sie unter Kontextreferenz. * password: Du kannst das automatisch generierte GITHUB_TOKEN-Geheimnis für das Kennwort verwenden. Weitere Informationen finden Sie unter Verwenden von GITHUB_TOKEN für die Authentifizierung in Workflows.

Die metadata-action erforderliche GitHub Packages Option ist: * images: Dies ist der Namespace und der Name für das Docker-Image, das du erstellst.

Die erforderlichen build-push-action Optionen für GitHub Packages sind:

  •         `context`: Definiert den Kontext des Builds als die Gruppe von Dateien, die sich im angegebenen Pfad befinden.

  •         `push`: Bei Festlegung auf `true`, wird das Image an die Registrierung übertragen, wenn es erfolgreich erstellt wurde.

  •         `tags` und `labels`: Diese werden von der Ausgabe von `metadata-action` gefüllt.

Hinweis

  • Dieser Workflow verwendet Aktionen, die nicht von GitHub zertifiziert wurden. Sie werden von einem Drittanbieter bereitgestellt und unterliegen separaten Nutzungsbedingungen, Datenschutzrichtlinien und Supportdokumentationen.
  • Wenn du einen SHA auswählen, solltest du überprüfen, ob er aus dem Repository der Aktion und nicht aus einem Repositoryfork stammt.
YAML
name: Create and publish a Docker image
on:
  push:
    branches: ['release']

Configures this workflow to run every time a change is pushed to the branch called release.

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.

jobs:
  build-and-push-image:
    runs-on: ubuntu-latest

There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.

    permissions:
      contents: read
      packages: write
      attestations: write
      id-token: write

Sets the permissions granted to the GITHUB_TOKEN for the actions in this job.

    steps:
      - name: Checkout repository
        uses: actions/checkout@v5
      - name: Log in to the Container registry
        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

Uses the docker/login-action action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

This step uses docker/metadata-action to extract tags and labels that will be applied to the specified image. The id "meta" allows the output of this step to be referenced in a subsequent step. The images value provides the base name for the tags and labels.

      - name: Build and push Docker image
        id: push
        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

This step uses the docker/build-push-action action to build the image, based on your repository's Dockerfile. If the build succeeds, it pushes the image to GitHub Packages. It uses the context parameter to define the build's context as the set of files located in the specified path. For more information, see Usage in the README of the docker/build-push-action repository. It uses the tags and labels parameters to tag and label the image with the output from the "meta" step.

      - name: Generate artifact attestation
        uses: actions/attest@v4
        with:
          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
          subject-digest: ${{ steps.push.outputs.digest }}
          push-to-registry: true

This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see Using artifact attestations to establish provenance for builds.

#
name: Create and publish a Docker image

# Configures this workflow to run every time a change is pushed to the branch called `release`.
on:
  push:
    branches: ['release']

# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
jobs:
  build-and-push-image:
    runs-on: ubuntu-latest
    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
    permissions:
      contents: read
      packages: write
      attestations: write
      id-token: write
      #
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5
      # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
      - name: Log in to the Container registry
        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
      # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
      # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see [Usage](https://github.com/docker/build-push-action#usage) in the README of the `docker/build-push-action` repository.
      # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
      - name: Build and push Docker image
        id: push
        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
      
      # This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see [Using artifact attestations to establish provenance for builds](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).
      - name: Generate artifact attestation
        uses: actions/attest@v4
        with:
          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
          subject-digest: ${{ steps.push.outputs.digest }}
          push-to-registry: true

Der obige Workflow wird durch einen Push an den Branch „release“ ausgelöst. Es checkt das GitHub Repository aus und verwendet die login-action, um sich beim Container registry anzumelden. Anschließend werden Bezeichnungen und Tags für das Docker-Image extrahiert. Schließlich wird die build-push-action Aktion verwendet, um das Image zu erstellen und es auf dem Container registry zu veröffentlichen.

Veröffentlichen von Bildern in Docker Hub und GitHub Packages

Du kannst dein Docker-Image mithilfe der Aktionen login-action und build-push-action für jede Registrierung in einem einzigen Workflow an mehrere Registrierungen pushen.

Im folgenden Beispielworkflow werden die Schritte aus den vorherigen Abschnitten (Publishing images to Docker Hub and Publishing images to GitHub Packages) verwendet, um einen einzelnen Workflow zu erstellen, der an beide Registrierungen überträgt.

YAML
# Dieser Workflow verwendet Aktionen, die nicht von GitHub zertifiziert sind.
# Sie werden von einem Drittanbieter bereitgestellt und unterliegen
# separaten Nutzungsbedingungen, Datenschutzbestimmungen und Support
# Onlinedokumentation.

# GitHub empfiehlt, Aktionen an einen Commit-SHA anzuheften.
# Um eine neuere Version zu erhalten, musst du den SHA aktualisieren.
# Du kannst auch auf ein Tag oder einen Branch verweisen, aber die Aktion kann sich ohne Vorwarnung ändern.

name: Publish Docker image

on:
  release:
    types: [published]

jobs:
  push_to_registries:
    name: Push Docker image to multiple registries
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read
    steps:
      - name: Check out the repo
        uses: actions/checkout@v5

      - name: Log in to Docker Hub
        uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Log in to the Container registry
        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
        with:
          images: |
            my-docker-hub-namespace/my-docker-hub-repository
            ghcr.io/${{ github.repository }}

      - name: Build and push Docker images
        id: push
        uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

Der obige Workflow checkt das GitHub Repository aus, verwendet das login-action zweimal, um sich bei den Registries anzumelden, und generiert Tags und Labels mit der metadata-action Aktion. Anschließend erstellt die Aktion build-push-action und verschiebt das Docker-Image auf Docker Hub und das Container registry.

Hinweis

Beim Übertragen auf mehrere Register:

  • Image-Digests können von Registrierung zu Registrierung unterschiedlich sein, was die Überprüfung des Nachweises erschwert.
  • Um einen konsistenten Digest zu erhalten und einem einzigen Nachweis die Möglichkeit zu bieten, alle Kopien zu verifizieren, pushes zuerst in eine Registrierung und verwende ein Tool wie crane copy, um das Image an anderer Stelle zu replizieren.
  • Wenn Sie sich stattdessen dafür entscheiden, jede Registrierung separat zu erstellen und zu übertragen, müssen Sie einen eindeutigen Nachweis für jeden generieren, um sicherzustellen, dass Ihre Artefakte überprüft werden können.

Praktische Übungen

Üben Sie die Veröffentlichung von Docker-Images mit der Übung zum Veröffentlichen von Docker-ImagesGitHub Skills .

In dieser Übung erfahren Sie, wie Sie:

  • Authentifizieren Sie sich bei GitHub Packages mithilfe von GITHUB_TOKEN.
  • Erstellen und veröffentlichen Sie Container-Images auf dem Container registry (ghcr.io).
  • Verwenden Sie offizielle Docker-Aktionen, wie z. B. docker/login-action, docker/build-push-action und docker/setup-buildx-action.
  • Generieren Sie Tags automatisch mit docker/metadata-action basierend auf Verzweigungen, Pullanforderungen und Freigaben.
  • Erstellen Sie Features, Pullanforderungen und Versionen mit der richtigen Containerversionsverwaltung.