GitHub Container Registry: So pushst du Docker Images zu GitHub

Die GitHub Container Registry ermöglicht dir das veröffentlichen bzw. hosten von privaten und öffentlichen Docker Images. Alles was dazu wichtig ist, erfährst du in diesem Tutorial.

GitHub stellt mit seinem Registry Service GitHub Packages eine Möglichkeit bereit, Entwicklern eigene Docker Images direkt in GitHub zu hosten. Dabei ist die Benennung von GitHub in meinen Augen etwas irreführend: Der Überbegriff des Dienstes ist GitHub Packages. Darin befinden sich einige Registries. Unter anderem die Docker Registry, welche aber in Container Registry umbenannt wurde, um sämtliche Arten von Containern zu hosten.

Warum nicht Docker Hub nutzen?

Der Docker Hub ist die erste Anlaufstelle, wenn es um Docker Images geht – keine Frage. In der kostenlosen Version steht jedem Account jedoch nur ein privates Image zur Verfügung und auch die Anzahl der Pulls (200 Pulls pro 6 Stunden) ist begrenzt. Und hier kommt die GitHub Container Registry zum Einsatz! 🙂

Docker Images in die GitHub Container Registry pushen

Um ein Docker Image zu erstellen, benötigen wir ein Docker Image, welches wir mit einer Dockerfile erstellen müssen. Ein solches Dockerfile kannst du beispielsweise über den docker init Befehl erstellen. Ist die Datei vorhanden können wir das Image bauen:

docker build -t frontend .

Im nächsten Schritt müssen wir uns an der GitHub Container Registry anmelden. Dazu benötigen wir einen Personal Access Token von GitHub.

Personal Access Token (PAT) generieren

Um einen neuen PAT zu generieren, navigierst du zu GitHub Settings > Developer seettings > Personal access tokens > Tokens (classic) und erstellst einen neuen Token. Als Scope musst du „write:packages“ und „read:packages“ auswählen. Die Laufzeit des Tokens kannst du an dein Projekt anpassen oder auf unbegrenzt stellen.

Den Token solltest du dir abspeichern, z.B. in deinen Passwort-Manager. Wenn du den Token verlierst, musst du ihn neu generieren.

Öffne jetzt ein Terminal an deinem Rechner und setze deinen PAT in eine Variable (ersetze <YOUR_PAT> durch deinen Token):

# Set PAT into a variable
export GH_PAT=<YOUR_PAT>

Um sich nun an der GitHub Container Registry (ghcr.io) anzumelden, nutze folgenden Befehl (ersetze <USERNAME> durch deinen GitHub Nutzernamen).

# Login to the GitHub Container Registry using your PAT
echo $GH_PAT | docker login ghcr.io -u <USERNAME> --password-stdin

War der PAT und dein Benutzername richtig, solltest du die Meldung „Login Succeeded“ erhalten.

Als nächsten taggen wir das Image, damit es auch in die korrekte Registry gelangt. Zu ersetzen ist hier <USERNAME> mit deinem GitHub Username, <IMAGE_NAME> mit dem gewünschten Namen des Images und <TAG> mit dem gewünschten Tag (Standard: latest)

# Tag the builded docker image
docker tag frontend ghcr.io/<USERNAME>/<IMAGE_NAME>:<TAG>

Jetzt können wir das Image in die Registry pushen. Hier musst du wieder die gleichen Variablen ersetzen wie beim Taggen:

docker push ghcr.io/<USERNAME>/<IMAGE_NAME>:<TAG>

Hast du alles richtig gemacht, solltest du eine solche Ausgabe erhalten bzw. keine Fehlermeldung 😉

Glückwunsch! Du hast erfolgreich dein erstes Docker Image in die GitHub Registry gepusht!

Auf dieser Seite hast du jetzt noch weitere Optionen, wie das Ändern der Sichtbarkeit oder das Löschen des Images.

GitHub Docker Images pullen

Natürlich kannst du jetzt auch deine Docker Images aus der Registry nutzen. Der Pfad ist wie beim Pushen:

docker pull ghcr.io/<USERNAME>/<IMAGE_NAME>:<TAG>

GitHub Actions Workflow für Docker Images in der GitHub Container Registry

Manuell Docker Images zu pushen ist doof! Daher gibt es CI/CD Pipelines, welche wir z.B. mit GitHub Actions umsetzen können. Bei bestimmten Events, z.B. einem neuen Commit können wir das Docker Image automatisch bauen und in der Registry veröffentlichen. In dem folgenden Beispiel wird ein Docker Image beim Push auf den frontend Branch gebaut und veröffentlicht. Das Bauen und veröffentlichen ist bereits nach dem Schritt „Build and push Docker image“ erledigt. Die beiden letzten Schritte habe ich dir aber zur Vollständigkeit mal drin gelassen, da das ein Workflow eines meiner Projekte ist und du vielleicht auch einen Anwendungsfall dafür hast 😉

In deinem GitHub Repository kannst du einfach eine Datei unter .github/workflows/cd.yml anlegen.

name: Continuous Deployment - Frontend

on:
  push:
    branches: ['frontend']

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

jobs:
  build-and-push-image:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      attestations: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

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

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

      - 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 }}

      - name: Install SSH client
        run: sudo apt-get update && sudo apt-get install -y openssh-client

      - name: Deploy to VM
        env:
          SSH_HOST: ${{ vars.SSH_HOST }}
          SSH_USER: ${{ secrets.SSH_USER }}
          SERVER_SSH_KEY: ${{ secrets.SERVER_SSH_KEY }}
          IMAGE_TAG: ${{ steps.meta.outputs.tags }}
        run: |
          echo "${{ env.SERVER_SSH_KEY }}" > key.pem
          chmod 600 key.pem
          ssh -i key.pem -o StrictHostKeyChecking=no ${{ env.SSH_USER }}@${{ env.SSH_HOST }} << 'EOF'
            docker login ${{ env.REGISTRY }} -u ${{ github.actor }} -p ${{ secrets.MY_PERSONAL_PAT }}
            docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ env.IMAGE_TAG }}
            cd ~
            docker compose down frontend
            docker compose up -d frontend
          EOF
          # Clean up the private key.pem
          rm key.pem

Und nicht vergessen: In den Repository Einstellungen die verwendeten Secrets und Variablen anlegen. In diesem Fall:

• Secrets:
  • MY_PERSONAL_PAT
  • SERVER_SSH_KEY
  • SSH_USER
• Variablen:
  • SSH_HOST

GitHub Container Registry: Fazit

That’s it! Das Bauen und Veröffentlichen von Docker Images in der GitHub Docker Registry bzw. GitHub Container Registry ist sehr ähnlich zum Docker Hub. Lediglich der Login über den GitHub PAT ist etwas komplizierter, bietet aber auch Vorteile bzgl. Berechtigungsmanagement, etc. Wirst du zukünftig die GitHub Packages Registry nutzen?