Arbeiten mit der Containerregistrierung

Informationen zur Container registry

Die Container registry speichert Containerimages innerhalb deiner Organisation oder deines persönlichen Kontos und ermöglicht es dir, ein Image einem Repository zuzuordnen. Du kannst wählen, ob Berechtigungen von einem Repository geerbt oder präzise Berechtigungen unabhängig von einem Repository festgelegt werden sollen. Du kannst auch anonym auf öffentliche Containerimages zugreifen.

Container registry: Unterstützung

Die Container registry unterstützt derzeit die folgenden Containerimageformate:

• Docker-Imagemanifest, Version 2, Schema 2
• Spezifikationen der Open Container Initiative (OCI)

Bei der Installation oder Veröffentlichung eines Docker-Image unterstützt die Container registry Fremdebenen wie z. B. Windows-Images.

Authentifizieren bei der Container registry

Du benötigst ein Zugriffstoken, um private, interne und öffentliche Pakete zu veröffentlichen, zu installieren und zu löschen.

Du kannst ein personal access token (classic) für die Authentifizierung bei GitHub Packages oder bei der GitHub-API verwenden. Wenn du ein personal access token (classic) erstellst, kannst du dem Token je nach Bedarf verschiedene Bereiche zuweisen. Weitere Informationen zu paketbezogenen Bereichen für ein personal access token (classic) findest du unter Informationen zu Berechtigungen für GitHub-Pakete.

Um dich bei einer GitHub Packages-Registrierung innerhalb eines GitHub Actions-Workflows zu authentifizieren, kannst du Folgendes verwenden:

• GITHUB_TOKEN, um Pakete zu veröffentlichen, die mit dem Workflowrepository verbunden sind.
• Ein personal access token (classic) (diesem muss mindestens der Bereich read:packages zugeordnet sein), um Pakete zu installieren, die zu anderen privaten Repositorys gehören (auf die GITHUB_TOKEN nicht zugreifen kann)

Authentifizieren in einem GitHub Actions-Workflow

Diese Registrierung unterstützt präzise Berechtigungen. Wenn dein GitHub Actions-Workflow ein personal access token zum Authentifizieren bei einer Registrierung verwendet, solltest du für Registrierungen, die differenzierte Berechtigungen unterstützen, deinen Workflow unbedingt so aktualisieren, dass das GITHUB_TOKEN verwendet wird. Eine Anleitung zum Aktualisieren deiner Workflows, die sich mit einem personal access token bei einer Registrierung authentifizieren, findest du unter Veröffentlichen und Installieren eines Pakets mit GitHub Actions.

Sie können ein GITHUB_TOKEN in einem GitHub Actions-Workflow verwenden, um ein Paket mithilfe der REST-API zu löschen oder wiederherzustellen, wenn das Token über die admin-Berechtigung für das Paket verfügt. Repositorys, die Pakete mithilfe eines Workflows veröffentlichen, und Repositorys, die du explizit mit Paketen verbunden hast, erhalten automatisch die admin-Berechtigung für Pakete im Repository.

Weitere Informationen zum GITHUB_TOKEN findest du unter Automatische Tokenauthentifizierung. Weitere Informationen zu den Best Practices bei der Verwendung einer Registrierung in Actions findest du unter Sicherheitshärtung für GitHub Actions.

Du kannst außerdem auswählen, ob du Zugriffsberechtigungen auf Pakete unabhängig voneinander für GitHub Codespaces und GitHub Actions erteilen möchtest. Weitere Informationen findest du unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen und unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen.

Authentifizierung mit personal access token (classic)

1. Erstelle ein neues personal access token (classic) mit den geeigneten Bereichen für die Aufgaben, die du erledigen möchtest. Wenn für deine Organisation SSO notwendig ist, musst du SSO für dein neues Token aktivieren.

   Hinweis: Wenn du auf der Benutzeroberfläche den Bereich write:packages für dein personal access token (classic) auswählst, wird standardmäßig auch der Bereich repo ausgewählt. Der Bereich repo bietet unnötigen und weitreichenden Zugriff, den du vor allem für GitHub Actions-Workflows vermeiden solltest. Weitere Informationen findest du unter Sicherheitshärtung für GitHub Actions. Als Problemumgehung kannst du mit dieser URL nur den Bereich write:packages für dein personal access token (classic) auf der Benutzeroberfläche auswählen: https://github.com/settings/tokens/new?scopes=write:packages.

   • Wähle den Bereich read:packages aus, um Containerimages herunterzuladen und die zugehörigen Metadaten zu lesen.
   • Wähle den Bereich write:packages aus, um Containerimages herunter- und hochzuladen und die zugehörigen Metadaten zu lesen und zu schreiben.
   • Wähle den Bereich delete:packages aus, um Containerimages zu löschen.

   Weitere Informationen findest du unter Verwalten deiner persönlichen Zugriffstoken.

2. Speichere dein personal access token (classic). Du solltest dein Token als Umgebungsvariable speichern.

   export CR_PAT=YOUR_TOKEN
   

3. Melde dich mit der CLI für deinen Containertyp beim Container registry-Dienst unter ghcr.io an.

   $ echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin
   > Login Succeeded
   

Pushen von Containerimages

In diesem Beispiel wird die neueste Version von IMAGE_NAME gepusht.

docker push ghcr.io/NAMESPACE/IMAGE_NAME:latest

Ersetze NAMESPACE durch den Namen des persönlichen Kontos oder der Organisation, auf das bzw. die das Image festgelegt werden soll.

In diesem Beispiel wird die 2.5-Version des Image gepusht.

docker push ghcr.io/NAMESPACE/IMAGE_NAME:2.5

Wenn du ein Paket zum ersten Mal veröffentlichst, ist die Sichtbarkeit standardmäßig auf privat eingestellt. Informationen zum Ändern der Sichtbarkeit oder zum Festlegen von Zugriffsberechtigungen findest du unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen. Du kannst ein veröffentlichtes Paket über die Benutzeroberfläche oder die Befehlszeile mit einem Repositoy verknüpfen. Weitere Informationen findest du unter Verbinden eines Repositorys mit einem Paket.

Beim Pushen eines Containerimages über die Befehlszeile wird das Image standardmäßig nicht mit einem Repository verknüpft. Dies gilt auch, wenn das Image mit einem Namespace gekennzeichnet wird, der dem Repositorynamen entspricht, z. B. ghcr.io/octocat/my-repo:latest.

Die einfachste Möglichkeit, ein Repository mit einem Containerpaket zu verknüpfen, besteht in der Veröffentlichung des Pakets über einen Workflow mit ${{secrets.GITHUB_TOKEN}}. Dies liegt daran, dass das Repository, das den Workflow enthält, automatisch verknüpft wird. Beachte, dass GITHUB_TOKEN nicht über die Berechtigung zum Pushen des Pakets verfügt, wenn du zuvor ein Paket an denselben Namespace gepusht, das Paket aber nicht mit dem Repository verbunden hast.

Es wird empfohlen, Dockerfile die Bezeichnung org.opencontainers.image.source hinzuzufügen, um beim Veröffentlichen eines Images über die Befehlszeile eine Verbindung mit einem Repository herzustellen und gleichzeitig sicherzustellen, dass GITHUB_TOKEN über die entsprechenden Berechtigungen bei Verwendung eines GitHub Actions-Workflows verfügt. Weitere Informationen findest du in diesem Artikel unter Bezeichnen von Containerimages sowie unter Veröffentlichen und Installieren eines Pakets mit GitHub Actions.

Pullen von Containerimages

Pullen mit „digest“

Um sicherzustellen, dass du immer dasselbe Image verwendest, kannst du die exakte Version des Containerimage, die du pullen möchtest, mit dem SHA-Wert digest angeben.

1. Um den Digest-SHA-Wert zu finden, musst du docker inspect oder docker pull verwenden und den SHA-Wert nach Digest: kopieren.

   docker inspect ghcr.io/NAMESPACE/IMAGE_NAME
   

   Ersetze NAMESPACE durch den Namen des persönlichen Kontos oder der Organisation, auf das bzw. die das Image festgelegt ist.

2. Entferne das Image nach Bedarf lokal.

   docker rmi  ghcr.io/NAMESPACE/IMAGE_NAME:latest
   

3. Pulle das Containerimage mit @YOUR_SHA_VALUE dem Imagenamen.

   docker pull ghcr.io/NAMESPACE/IMAGE_NAME@sha256:82jf9a84u29hiasldj289498uhois8498hjs29hkuhs
   

Pullen nach Name

docker pull ghcr.io/NAMESPACE/IMAGE_NAME

Ersetze NAMESPACE durch den Namen des persönlichen Kontos oder der Organisation, auf das bzw. die das Image festgelegt ist.

Pullen nach Name und Version

Dieses Docker-CLI-Beispiel zeigt ein Image, das nach Namen und 1.14.1-Versionstag gepullt wurde:

$ docker pull ghcr.io/NAMESPACE/IMAGE_NAME:1.14.1
> 5e35bd43cf78: Pull complete
> 0c48c2209aab: Pull complete
> fd45dd1aad5a: Pull complete
> db6eb50c2d36: Pull complete
> Digest: sha256:ae3b135f133155b3824d8b1f62959ff8a72e9cf9e884d88db7895d8544010d8e
> Status: Downloaded newer image for ghcr.io/NAMESPACE/IMAGE_NAME/release:1.14.1
> ghcr.io/NAMESPACE/IMAGE_NAME/release:1.14.1

Ersetze NAMESPACE durch den Namen des persönlichen Kontos oder der Organisation, auf das bzw. die das Image festgelegt ist.

Pullen nach Name und neuester Version

$ docker pull ghcr.io/NAMESPACE/IMAGE_NAME:latest
> latest: Pulling from NAMESPACE/IMAGE_NAME
> Digest: sha256:b3d3e366b55f9a54599220198b3db5da8f53592acbbb7dc7e4e9878762fc5344
> Status: Downloaded newer image for ghcr.io/NAMESPACE/IMAGE_NAME:latest
> ghcr.io/NAMESPACE/IMAGE_NAME:latest

Ersetze NAMESPACE durch den Namen des persönlichen Kontos oder der Organisation, auf das bzw. die das Image festgelegt ist.

Erstellen von Containerimages

In diesem Beispiel wird das Image hello_docker erstellt:

docker build -t hello_docker .

Taggen von Containerimages

1. Suche die ID des Docker-Image, das du taggen möchten.

   $ docker images
   > REPOSITORY                                            TAG                 IMAGE ID            CREATED             SIZE
   > ghcr.io/my-org/hello_docker         latest            38f737a91f39        47 hours ago        91.7MB
   > hello-world                                           latest              fce289e99eb9        16 months ago       1.84kB
   

2. Tagge dein Docker-Image mithilfe der Image-ID, des gewünschten Imagenamens und des gewünschten Hostingziels.

   docker tag 38f737a91f39 ghcr.io/NAMESPACE/NEW_IMAGE_NAME:latest
   

Ersetze NAMESPACE durch den Namen des persönlichen Kontos oder der Organisation, auf das bzw. die das Image festgelegt werden soll.

Bezeichnen von Containerimages

Du kannst deinem Containerimage mithilfe von vordefinierten Anmerkungsschlüsseln Metadaten hinzufügen, z. B. eine Beschreibung, eine Lizenz und ein Quellrepository. Werte für unterstützte Schlüssel werden auf der Paketseite für das Image angezeigt.

Für die meisten Images kannst du Docker-Bezeichnungen verwenden, um einem Image die Anmerkungsschlüssel hinzuzufügen. Weitere Informationen findest du unter LABEL in der offiziellen Docker-Dokumentation und unter Vordefinierte Anmerkungsschlüssel im Repository opencontainers/image-spec.

Bei Multi-Arch-Images kannst du dem Image eine Beschreibung hinzufügen, indem du dem Feld annotations im Imagemanifest den entsprechenden Anmerkungsschlüssel hinzufügst. Weitere Informationen findest du unter Hinzufügen einer Beschreibung zu Multi-Arch-Images.

Die folgenden Anmerkungsschlüssel werden in der Container registry unterstützt.

Schlüssel	BESCHREIBUNG
org.opencontainers.image.source	Die URL des Repositorys, das dem Paket zugeordnet ist. Weitere Informationen findest du unter Verbinden eines Repositorys mit einem Paket.
org.opencontainers.image.description	Eine reine Textbeschreibung, die auf 512 Zeichen beschränkt ist. Diese Beschreibung wird auf der Paketseite unter dem Namen des Pakets angezeigt.
org.opencontainers.image.licenses	Ein SPDX-Lizenzbezeichner wie MIT, der auf 256 Zeichen beschränkt ist. Die Lizenz wird auf der Paketseite auf der Randleiste „Details“ angezeigt. Weitere Informationen findest du unter SPDX-Lizenzliste.

Um einen Schlüssel als Docker-Bezeichnung hinzuzufügen, empfiehlt es sich, die LABEL-Anweisung in deines Dockerfile zu verwenden. Wenn du beispielsweise der Benutzer bzw. die Benutzerin octocat bist, dir my-repo gehört und dein Image unter den Bedingungen der MIT-Lizenz verteilt wird, musst du deinem Dockerfile die folgenden Zeilen hinzufügen:

LABEL org.opencontainers.image.source=https://github.com/octocat/my-repo
LABEL org.opencontainers.image.description="My container image"
LABEL org.opencontainers.image.licenses=MIT

Alternativ kannst du einem Image auch mit dem Befehl docker build zur Buildzeit Bezeichnungen hinzufügen.

$ docker build \
 --label "org.opencontainers.image.source=https://github.com/octocat/my-repo" \
 --label "org.opencontainers.image.description=My container image" \
 --label "org.opencontainers.image.licenses=MIT"

Hinzufügen einer Beschreibung zu Multi-Arch-Images

Ein Multi-Arch-Image ist ein Image, das mehrere Architekturen unterstützt. Es funktioniert, indem innerhalb eines einzelnen Manifests auf eine Liste von Images verwiesen wird, die jeweils eine andere Architektur unterstützen.

Die Beschreibung, die auf der Paketseite für ein Multi-Arch-Image angezeigt wird, wird aus dem annotations-Feld im Imagemanifest abgerufen. Wie Docker-Bezeichnungen bieten Anmerkungen eine Möglichkeit, Metadaten einem Image zuzuordnen und vordefinierte Anmerkungsschlüssel zu unterstützen. Weitere Informationen findest du unter Anmerkungen im opencontainers/image-spec-Repository.

Um eine Beschreibung für ein Multi-Arch-Image bereitzustellen, lege wie folgt einen Wert für den org.opencontainers.image.description-Schlüssel im Feld annotations des Manifests fest.

"annotations": {
  "org.opencontainers.image.description": "My multi-arch image"
}

Der folgende GitHub Actions-Workflowschritt erstellt und pusht beispielsweise ein Multi-Arch-Image. Der outputs-Parameter legt die Beschreibung für das Image fest.

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

- name: Build and push Docker image
  uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
  with:
    context: .
    file: ./Dockerfile
    platforms: ${{ matrix.platforms }}
    push: true
    outputs: type=image,name=target,annotation-index.org.opencontainers.image.description=My multi-arch image

Problembehandlung

• Container registry hat eine Größenbeschränkung von 10 GB für jede Ebene.
• Container registry hat ein Zeitlimit von 10 Minuten für Uploads.