Docker Hub : publier vos images (push/pull), PAT et CI/CD GitHub Actions

Vous voulez publier vos images Docker pour les déployer sur vos serveurs ? Docker Hub est la registry publique la plus utilisée au monde. Ce guide vous montre comment créer un compte, configurer l’authentification par token (PAT), et automatiser vos builds avec GitHub Actions — le tout en respectant les nouvelles limites de 2025.

Ce que vous allez apprendre

À la fin de ce guide, vous serez capable de gérer l’ensemble du cycle de vie de vos images Docker sur Docker Hub — de la création du compte jusqu’à l’automatisation complète en CI/CD.

• Créer un compte et comprendre les différents plans (gratuit vs payant)
• Configurer un Personal Access Token (PAT) — obligatoire depuis 2024
• Publier une image avec docker push (et la récupérer avec docker pull)
• Automatiser vos builds avec GitHub Actions
• Choisir les bonnes images parmi les 3 types de contenu de confiance
• Éviter le rate limiting et les erreurs 429 Too Many Requests

Prérequis

Comprendre les registries de conteneurs Vocabulaire, fonctionnement de docker pull/push, standards OCI

Écrire un Dockerfile Créer votre première image Docker

Qu’est-ce que Docker Hub ?

Docker Hub est la registry publique officielle de Docker — un serveur qui stocke et distribue des images de conteneurs. C’est l’équivalent de GitHub pour le code, mais pour les images Docker.

Quelques chiffres :

• Plus de 100 millions d’images disponibles
• Plus de 13 millions de développeurs inscrits
• Images officielles maintenues par Docker (nginx, postgres, redis…)
• Intégration native avec Docker Desktop et la CLI

Analogie : si vous connaissez npm pour JavaScript ou PyPI pour Python, Docker Hub joue le même rôle pour les images de conteneurs. Vous publiez vos images, d’autres les téléchargent.

Les 3 types de contenu de confiance

Docker Hub ne contient pas que des images de qualité égale. Il existe 3 niveaux de confiance officiels :

Type	Badge	Qui maintient ?	Exemples
Official Images	🛡️ Vert	Docker + communauté	nginx, postgres, redis, ubuntu
Verified Publishers	✓ Bleu	Éditeurs commerciaux vérifiés	bitnami, microsoft, canonical
Sponsored OSS	🌐 Violet	Projets open source sponsorisés	grafana, traefik, prometheus

Glissez pour voir

Images communautaires

Les images sans badge sont publiées par des utilisateurs quelconques. Scannez-les toujours avec Docker Scout ou Trivy avant utilisation. Elles peuvent contenir des vulnérabilités ou du code malveillant.

Créer un compte Docker Hub

1. Accéder au site

   Rendez-vous sur hub.docker.com et cliquez sur Sign Up en haut à droite.

2. Remplir le formulaire

   • Username : ce sera votre namespace (ex: monuser/monimage)
   • Email : pour la confirmation et les notifications
   • Password : minimum 9 caractères, avec majuscules et chiffres

3. Confirmer votre email

   Docker envoie un email de vérification. Cliquez sur le lien dans les 24h.

4. Se connecter

   Retournez sur Docker Hub et connectez-vous. Vous accédez à votre tableau de bord.

Compte gratuit vs payant : que choisir ?

Docker Hub propose plusieurs formules adaptées à différents besoins. Le choix dépend principalement de trois facteurs : le nombre de dépôts privés dont vous avez besoin, votre volume de pulls, et si vous travaillez en équipe.

Fonctionnalité	Personal (gratuit)	Pro ($5/mois)	Team ($9/user/mois)
Dépôts publics	Illimités	Illimités	Illimités
Dépôts privés	1	Illimités	Illimités
Pulls/heure (authentifié)	100	5 000	5 000
Pulls/heure (anonyme)	10/IP	—	—
Docker Scout	Limité	3 repos	Illimité
Équipes & RBAC	❌	❌	✅

Glissez pour voir

Conseil

Pour un usage personnel ou des projets open source, le compte gratuit suffit. Passez à Pro/Team uniquement si vous atteignez les limites de rate limiting ou si vous avez besoin de dépôts privés multiples.

Configurer l’authentification par token (PAT)

Changement important 2024-2026

Depuis septembre 2024, les mots de passe sont progressivement désactivés pour docker login. En 2026, seuls les Personal Access Tokens (PAT) et le SSO seront acceptés. Configurez vos PAT dès maintenant.

Pourquoi utiliser un PAT plutôt qu’un mot de passe ?

Les Personal Access Tokens (PAT) offrent une sécurité bien supérieure aux mots de passe traditionnels. Imaginez que vous utilisez le même mot de passe pour votre laptop, votre CI/CD et un script de déploiement : si l’un est compromis, tout est compromis. Avec les PAT, vous créez un token par usage, chacun avec des permissions limitées et une date d’expiration.

Critère	Mot de passe	Personal Access Token
Révocation	Impossible sans changer partout	Révocable individuellement
Permissions	Accès total au compte	Read, Write, ou Delete séparés
Expiration	Jamais	Configurable (30, 60, 90 jours…)
Audit	Aucune traçabilité	Logs d’utilisation
2FA compatible	❌ Bloqué si 2FA activé	✅ Fonctionne toujours

Glissez pour voir

Créer un Personal Access Token

1. Accéder aux paramètres de sécurité

   Connectez-vous à Docker Hub → Cliquez sur votre avatar → Account Settings → Security → Personal access tokens.

2. Générer un nouveau token

   Cliquez sur Generate new token et configurez :

   • Description : nom explicite (ex: github-actions-prod, laptop-dev)
   • Expiration : 90 jours recommandé pour la CI/CD
   • Permissions :
     • Read : pour docker pull uniquement
     • Read & Write : pour docker push et docker pull
     • Read, Write & Delete : accès complet (éviter en CI/CD)

3. Copier le token immédiatement

   Le token n’est affiché qu’une seule fois. Copiez-le dans un gestionnaire de secrets (Vault, 1Password, GitHub Secrets…).

4. Tester la connexion

   # Connexion avec le PAT (remplacez YOUR_TOKEN)
   echo "YOUR_TOKEN" | docker login -u votre-username --password-stdin
   
   # Résultat attendu
   Login Succeeded

Où est stocké le token ?

Le token est enregistré dans ~/.docker/config.json en clair par défaut. Pour plus de sécurité, utilisez un credential helper :

• macOS : osxkeychain
• Linux : pass ou secretservice
• Windows : wincred

Publier une image sur Docker Hub

Vous avez créé une image localement et voulez la partager ? Voici le workflow complet.

Préparer l’image

# 1. Construire l'image avec un tag local
docker build -t monapp:v1.0.0 .

# 2. Vérifier que l'image existe
docker images | grep monapp
# monapp    v1.0.0    abc123def456    2 minutes ago    150MB

Taguer pour Docker Hub

Le format du tag Docker Hub est : username/repository:tag

# 3. Taguer l'image pour Docker Hub
docker tag monapp:v1.0.0 monuser/monapp:v1.0.0

# Optionnel : ajouter un tag "latest"
docker tag monapp:v1.0.0 monuser/monapp:latest

Pousser l’image

# 4. Se connecter (si pas déjà fait)
echo "$DOCKER_TOKEN" | docker login -u monuser --password-stdin

# 5. Pousser l'image
docker push monuser/monapp:v1.0.0
docker push monuser/monapp:latest

Résultat attendu :

The push refers to repository [docker.io/monuser/monapp]
a3b52c...: Pushed
b4c63d...: Pushed
v1.0.0: digest: sha256:abc123... size: 1234

Vérifier sur Docker Hub

Rendez-vous sur https://hub.docker.com/r/monuser/monapp pour voir votre image publiée avec ses tags.

Récupérer une image depuis Docker Hub

# Pull d'une image officielle
docker pull nginx:1.25

# Pull d'une image utilisateur
docker pull monuser/monapp:v1.0.0

# Pull avec digest (immuable, recommandé en production)
docker pull nginx@sha256:a3b52c...

Astuce performance

Docker ne télécharge que les layers manquants. Si vous avez déjà une image basée sur debian:12, le pull d’une autre image debian:12 sera quasi instantané.

Automatiser avec GitHub Actions

L’approche moderne consiste à builder et pusher automatiquement vos images à chaque commit. Voici un workflow complet avec scan de sécurité.

Pourquoi piner les actions par SHA ?

Les tags comme @v4 peuvent être déplacés par le mainteneur de l’action. Un attaquant qui compromet le compte pourrait remplacer le code de @v4 par du code malveillant. En pinant par SHA (ex: @11bd71901...), vous utilisez une version immuable — le code ne peut pas changer sans que le SHA change. Ajoutez un commentaire # v4.2.2 pour faciliter les mises à jour. Plus d’infos

Configurer les secrets GitHub

Pour que GitHub Actions puisse pousser vos images, il a besoin de vos identifiants Docker Hub. Ne jamais les mettre en clair dans le workflow : utilisez les secrets GitHub qui sont chiffrés et injectés uniquement au runtime.

Dans votre repo GitHub : Settings → Secrets and variables → Actions → New repository secret :

Secret	Valeur
DOCKERHUB_USERNAME	Votre username Docker Hub
DOCKERHUB_TOKEN	Votre PAT avec permissions Read & Write

Glissez pour voir

Workflow GitHub Actions

Créez .github/workflows/docker-publish.yml :

name: Build and Push Docker Image

on:
  push:
    branches: [main]
    tags: ['v*']
  pull_request:
    branches: [main]

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

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

    steps:
      # Toutes les actions sont pinées par SHA pour la sécurité
      - name: Checkout code
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@988b5a0280414f521da01fcc63a27aeeb4b104db # v3.6.1

      - name: Login to Docker Hub
        if: github.event_name != 'pull_request'
        uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567 # v3.3.0
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Extract metadata (tags, labels)
        id: meta
        uses: docker/metadata-action@8e5442c4ef9f78752691e2d8f8d19755c6f78e81 # v5.5.1
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch
            type=semver,pattern={{version}}
            type=sha,prefix=

      - name: Build and push
        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Run Docker Scout scan
        if: github.event_name != 'pull_request'
        uses: docker/scout-action@f8c776824083494ab0d56b8105ba2ca85c86e4de # v1.18.2
        with:
          command: cves
          image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
          only-severities: critical,high
          exit-code: true

Ce que fait ce workflow

1. Checkout : récupère le code source
2. Buildx : active le builder moderne avec cache
3. Login : s’authentifie avec le PAT (sauf pour les PR)
4. Metadata : génère automatiquement les tags (main, v1.2.3, sha-abc123)
5. Build & Push : construit et pousse l’image
6. Scout : scanne les vulnérabilités et échoue si critique/haute

Gérer les organisations et équipes

Pour les projets d’équipe, Docker Hub propose des organisations avec gestion des accès (RBAC).

Créer une organisation

1. Docker Hub → Organizations → Create Organization
2. Choisissez un nom (ex: mon-entreprise)
3. Sélectionnez le plan (Team requis pour RBAC avancé)

Configurer les équipes et permissions

Le modèle de permissions de Docker Hub suit le principe du moindre privilège : chaque membre n’a accès qu’à ce dont il a besoin. Créez des teams par fonction (backend, frontend, devops) et assignez-leur des permissions spécifiques sur les repositories.

Rôle	Permissions
Owner	Accès total (facturation, membres, tous les repos)
Member	Accès aux repos assignés selon les teams
Read	Pull uniquement
Write	Pull + Push
Admin	Pull + Push + Gestion du repo

Glissez pour voir

Exemple de structure :

Organisation: mon-entreprise
├── Team: backend-devs
│   ├── Permissions: Write sur mon-entreprise/api-*
│   └── Membres: alice, bob
├── Team: devops
│   ├── Permissions: Admin sur tous les repos
│   └── Membres: charlie
└── Team: frontend-devs
    ├── Permissions: Read sur mon-entreprise/api-*
    └── Membres: diana

Éviter le rate limiting (erreur 429)

Depuis avril 2025, Docker Hub applique des limites strictes :

Type d’utilisateur	Limite
Anonyme (sans login)	10 pulls/heure/IP
Personal (gratuit, authentifié)	100 pulls/heure
Pro/Team	5 000 pulls/heure

Glissez pour voir

Symptômes du rate limiting

Error response from daemon: toomanyrequests: You have reached your pull
rate limit. You may increase the limit by authenticating...

Solutions

S'authentifier

La solution la plus simple : toujours se connecter, même pour les pulls.

# Dans vos scripts/CI
echo "$DOCKERHUB_TOKEN" | docker login -u $DOCKERHUB_USERNAME --password-stdin

# Ensuite vos pulls bénéficient de la limite authentifiée (100/h au lieu de 10/h)
docker pull nginx:1.25

Registry miroir

Configurez un proxy cache local avec Harbor ou un registry miroir :

/etc/docker/daemon.json

{
  "registry-mirrors": ["https://mirror.mon-entreprise.local"]
}

Le miroir cache les images et réduit drastiquement les pulls vers Docker Hub.

Compte Pro/Team

Pour les gros volumes (CI/CD intensif), passez à Pro ($5/mois) ou Team ($9/user/mois) pour 5 000 pulls/heure.

Vérifier votre consommation

# Après un docker pull, vérifiez les headers
TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/nginx:pull" | jq -r .token)

curl -s -D - -H "Authorization: Bearer $TOKEN" \
  https://registry-1.docker.io/v2/library/nginx/manifests/latest \
  2>&1 | grep -i ratelimit

# Résultat exemple :
# ratelimit-limit: 100;w=21600
# ratelimit-remaining: 95;w=21600

Sécurité : bonnes pratiques

Ne jamais stocker de secrets dans les images

# ❌ MAUVAIS : le secret reste dans l'historique des layers
RUN echo "API_KEY=abc123" >> /app/.env

# ✅ BON : utiliser des variables d'environnement au runtime
# docker run -e API_KEY=abc123 monimage

Scanner vos images avant publication

# Avec Docker Scout (intégré)
docker scout cves monuser/monapp:v1.0.0

# Avec Trivy (open source)
trivy image monuser/monapp:v1.0.0

Utiliser des tags versionnés, jamais latest en production

# ❌ MAUVAIS : latest peut changer à tout moment
image: monuser/monapp:latest

# ✅ BON : tag versionné ou digest
image: monuser/monapp:v1.2.3
image: monuser/monapp@sha256:abc123...

Créer des PAT avec permissions minimales

Chaque PAT devrait avoir exactement les permissions nécessaires, pas plus. Si un serveur de production n’a besoin que de récupérer des images, donnez-lui un token en lecture seule. Si ce token est compromis, l’attaquant ne pourra pas pousser d’images malveillantes.

Usage	Permissions recommandées
CI/CD (push)	Read & Write
Serveurs de prod (pull only)	Read
Développeur local	Read & Write
Scripts de nettoyage	Read, Write & Delete

Glissez pour voir

Dépannage

Voici les erreurs les plus fréquentes rencontrées avec Docker Hub et leurs solutions. Dans la majorité des cas, le problème vient de l’authentification (token expiré, mauvaises permissions) ou du rate limiting.

Symptôme	Cause probable	Solution
unauthorized: authentication required	Token invalide ou expiré	Régénérer un PAT, refaire docker login
denied: requested access to the resource is denied	Permissions insuffisantes	Vérifier les permissions du PAT (Write pour push)
toomanyrequests (429)	Rate limiting atteint	S’authentifier, utiliser un miroir, ou passer à Pro
manifest unknown	Tag inexistant	Vérifier le nom exact du tag sur Docker Hub
unauthorized: please use personal access token	Mot de passe au lieu de PAT	Créer un PAT et l’utiliser à la place du mot de passe

Glissez pour voir

À retenir

1. Docker Hub est la registry publique de référence avec plus de 100M d’images. Privilégiez les images avec badges (Official, Verified, Sponsored).

2. Les PAT remplacent les mots de passe depuis 2024. Créez-en un avec les permissions minimales nécessaires et stockez-le dans un gestionnaire de secrets.

3. Le rate limiting est strict : 10 pulls/h anonyme, 100 pulls/h authentifié. Connectez-vous toujours, même pour les pulls.

4. Automatisez vos builds avec GitHub Actions : build, scan avec Scout, push conditionnel. Utilisez les tags sémantiques et les digests.

5. Scannez avant de publier avec Docker Scout ou Trivy. Ne poussez jamais d’image avec des vulnérabilités critiques.

Prochaines étapes

Optimiser la taille de vos images Multi-stage builds, images minimales, bonnes pratiques

Harbor : registry privée on-premise Déployer votre propre registry avec scan et RBAC

Scanner vos images avec Trivy Détecter les vulnérabilités avant déploiement

Docker Compose Orchestrer plusieurs conteneurs localement

×

📖 Voir la documentation →