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 dieGITHUB_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 Bereichrepo
ausgewählt. Der Bereichrepo
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 Bereichwrite: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.
- Wähle den Bereich
-
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
oderdocker pull
verwenden und den SHA-Wert nachDigest:
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