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 Verwalten deiner persönlichen Zugriffstoken.
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 dieGITHUB_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.
Note
Die Möglichkeit für GitHub Actions-Workflows, Pakete mithilfe der REST-API zu löschen und wiederherzustellen, befindet sich derzeit in der public preview. Änderungen sind vorbehalten.
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)
GitHub Packages unterstützt nur die Authentifizierung mit einem personal access token (classic). Weitere Informationen findest du unter Verwalten deiner persönlichen Zugriffstoken.
-
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.
Note
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 Verwalten deiner persönlichen Zugriffstoken.
- 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/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.
-
Um den Digest-SHA-Wert zu finden, musst du
docker inspect
oderdocker pull
verwenden und den SHA-Wert nachDigest:
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. -
Entferne das Image nach Bedarf lokal.
docker rmi ghcr.io/NAMESPACE/IMAGE_NAME:latest
-
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
-
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
-
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
Note
Wenn du ein Paket veröffentlichst, das mit einem Repository verknüpft ist, erbt das Paket automatisch die Zugriffsberechtigungen des verknüpften Repositorys, und GitHub Actions-Workflows im verknüpften Repository erhalten automatisch Zugriff auf das Paket – es sei denn, deine Organisation hat die automatische Vererbung von Zugriffsberechtigungen deaktiviert. Weitere Informationen findest du unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen.
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.