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:

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

GitHub Packages unterstützt nur die Authentifizierung mit einem personal access token (classic). Weitere Informationen findest du unter Erstellen eines personal access token.

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 über paketbezogene Bereiche 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 packages:read 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 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. Anleitungen zum Aktualisieren deiner Workflows, die sich mit einem personal access token bei einer Registrierung authentifizieren, findest du unter Upgrade eines Workflows mit Registrierungszugriff über ein personal access token.

Weitere Informationen über das GITHUB_TOKEN findest du unter Authentifizierung in einem Workflow. 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 Sicherstellen des Codespaces-Zugriffs auf dein Paket sowie unter Sicherstellen des Workflowzugriffs auf dein Paket.

Authentifizierung mit personal access token (classic)

GitHub Packages unterstützt nur die Authentifizierung mit einem personal access token (classic). Weitere Informationen findest du unter Erstellen eines personal access token.

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 Erstellen eines personal access token für die Befehlszeile.
Speichere dein personal access token (classic). Du solltest dein Token als Umgebungsvariable speichern.
```
$ export CR_PAT=YOUR_TOKEN
```
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/OWNER/IMAGE_NAME:latest

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

$ docker push ghcr.io/OWNER/IMAGE_NAME:2.5

Wenn du ein Paket zum ersten Mal veröffentlichst, ist die Sichtbarkeit standardmäßig auf privat eingestellt. Wenn ein Paket mit einem Repository verknüpft ist, richtet sich die Sichtbarkeit des Pakets nach der Sichtbarkeit des Repositorys. Um die Sichtbarkeit zu ändern oder Zugriffsberechtigungen festzulegen, solltest du den Artikel Konfigurieren der Zugriffssteuerung und Sichtbarkeit eines Pakets. 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.

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.

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/OWNER/IMAGE_NAME
```

Entferne das Image nach Bedarf lokal.

$ docker rmi  ghcr.io/OWNER/IMAGE_NAME:latest

Pulle das Containerimage mit @YOUR_SHA_VALUE dem Imagenamen.

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

Pullen nach Name

$ docker pull ghcr.io/OWNER/IMAGE_NAME

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/OWNER/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/orgname/image-name/release:1.14.1
  > ghcr.io/orgname/image-name/release:1.14.1

Pullen nach Name und neuester Version

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

Erstellen von Containerimages

In diesem Beispiel wird das Image hello_docker erstellt:

$ docker build -t hello_docker .

Taggen von Containerimages

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
> ghcr.io/my-username/hello_docker    latest              38f737a91f39        47 hours ago        91.7MB
> hello-world                                           latest              fce289e99eb9        16 months ago       1.84kB

Tagge dein Docker-Image mithilfe der Image-ID, des gewünschten Imagenamens und des gewünschten Hostingziels.
```
$ docker tag 38f737a91f39 ghcr.io/OWNER/NEW_IMAGE_NAME:latest
```

Bezeichnen von Containerimages

You can use pre-defined annotation keys to add metadata including a description, a license, and a source repository to your container image. 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 monalisa 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/monalisa/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/monalisa/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@ad44023a93711e3deb337508980b4b5e9bcdc5dc
  with:
    context: .
    file: ./Dockerfile
    platforms: ${{ matrix.platforms }}
    push: true
    outputs: type=image,name=target,annotation-index.org.opencontainers.image.description=My multi-arch image