GitHub Container Registry (GHCR)

GitHub Container Registry (GHCR) est le registry d'images Docker intégré à GitHub. Il stocke les images au même endroit que le code source, partage la gestion des accès avec les dépôts GitHub, et s'intègre nativement dans les workflows GitHub Actions via le token GITHUB_TOKEN.

Différences avec Docker Hub

Critère	GHCR	Docker Hub
Images privées	Illimitées (inclus dans GitHub)	Limitées selon le plan
Authentification	GITHUB_TOKEN (automatique en CI)	Token personnel
Intégration CI	Native (même écosystème)	Via secrets
Visibilité	Liée au dépôt GitHub	Indépendante

Nommage des images

Les images GHCR suivent la convention :

ghcr.io/<owner>/<image-name>:<tag>

Où <owner> est le nom d'utilisateur GitHub ou l'organisation. Il est recommandé de tagger avec le SHA du commit pour garantir la traçabilité :

ghcr.io/my-org/api:latest
ghcr.io/my-org/api:1.2.3
ghcr.io/my-org/api:sha-a1b2c3d

Chaque déploiement peut ainsi être retracé jusqu'au commit exact dont l'image a été construite.

Workflow GitHub Actions

Le workflow suivant construit et publie une image à chaque push sur main :

name: Build and push Docker image

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=sha
            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Points clés :

• permissions.packages: write est nécessaire pour pousser vers GHCR
• GITHUB_TOKEN est généré automatiquement par GitHub Actions — aucun secret à configurer manuellement
• cache-from: type=gha utilise le cache GitHub Actions pour accélérer les builds successifs
• docker/metadata-action génère automatiquement les tags et labels OCI standards

Utiliser une image GHCR dans un workflow

Une image GHCR peut servir de conteneur d'exécution pour un job GitHub Actions. Si le dépôt est privé, le GITHUB_TOKEN donne automatiquement accès aux packages privés de la même organisation — sans PAT supplémentaire.

jobs:
  run-in-container:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/my-org/my-image:latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: pytest

Authentification locale

Pour pull une image privée depuis une machine locale :

# Créer un Personal Access Token avec le scope "read:packages"
# dans GitHub Settings → Developer settings → Personal access tokens

echo $GITHUB_PAT | docker login ghcr.io -u <username> --password-stdin

docker pull ghcr.io/my-org/api:latest

Visibilité des packages

Par défaut, un package GHCR hérite de la visibilité du dépôt source. La visibilité se modifie dans l'onglet Packages du profil GitHub ou de l'organisation → sélectionner le package → Package settings → Change visibility.

L'accès à un package privé se gère séparément du dépôt : il est possible de donner accès à une image sans donner accès au code source.

Nettoyage des anciennes versions

Chaque push crée une nouvelle version du package. Sans nettoyage, les versions s'accumulent. GitHub propose une action dédiée :

- name: Delete old package versions
  uses: actions/delete-package-versions@v5
  with:
    package-name: api
    package-type: container
    min-versions-to-keep: 10
    delete-only-untagged-versions: true

delete-only-untagged-versions: true supprime uniquement les images sans tag (les builds intermédiaires), en conservant toutes les images taguées explicitement.