Récupérer des images Docker Hub via le proxy de dépendances avec votre propre jeton Docker Hub

fremforge ne récupère pas d’images Docker Hub pour votre compte avec un compte partagé. Les conditions de Docker autorisent l’accès pour vos propres besoins internes, et Docker Hub limite les pulls anonymes par adresse IP, une limite partagée par tous ceux qui se trouvent derrière cette adresse. Docker Hub fonctionne donc comme le proxy de dépendances de GitLab et les caches pull-through d’Amazon ECR : votre organisation fournit son propre jeton Docker Hub, et le proxy de dépendances récupère et met en cache les images avec celui-ci.

Vous disposez alors de deux façons de récupérer une image Docker Hub :

Les runners hébergés par fremforge n’utilisent plus de miroir Docker Hub partagé. Tant que votre organisation n’a pas enregistré son jeton Docker Hub, un simple docker pull node:24 dans un workflow est un pull anonyme direct depuis Docker Hub, décompté de la limite de Docker pour l’adresse du runner. Une fois le jeton enregistré, et avec le pull-through des runners activé (par défaut), le démon Docker du runner fait passer les pulls Docker Hub de vos tâches par votre proxy avec ce jeton, sans aucune modification des noms d’image, sauf dans les tâches issues de pull requests provenant de forks. Voir Runners hébergés.

Avant de commencer

• Le proxy de dépendances doit être activé pour l’organisation. Il est disponible dans toutes les offres et activé par défaut ; un propriétaire qui l’a désactivé le réactive sous Paramètres de l’organisation > Proxy de dépendances (PUT /orgs/{org}/dependency-proxy avec "enabled": true).
• Vous devez être propriétaire de l’organisation pour enregistrer un identifiant.

Créer un jeton d’accès Docker Hub

1. Connectez-vous à Docker Hub avec le compte que le proxy doit utiliser : un compte de service de votre entreprise vaut mieux que celui d’une personne.
2. Allez dans Account settings > Personal access tokens et sélectionnez Generate new token.
3. Nommez-le d’après son usage, par exemple fremforge dependency proxy, et définissez les permissions d’accès sur Public Repo Read-only. Le proxy ne fait jamais que lire.
4. Copiez le jeton. Docker Hub ne l’affiche qu’une fois.

Un jeton d’accès d’organisation d’une organisation Docker Hub fonctionne de la même façon.

L’enregistrer comme identifiant amont docker.io de votre organisation

Dans la console : Paramètres de l’organisation > Proxy de dépendances > Identifiants des registres en amont, sous Ajouter des identifiants. Choisissez le registre docker.io, réglez Méthode de connexion sur Nom d’utilisateur et mot de passe ou jeton, saisissez le nom d’utilisateur Docker Hub et le jeton comme mot de passe, puis sélectionnez Ajouter. Tester la connexion fait se connecter immédiatement le proxy à Docker Hub avec cet identifiant.

Avec l’API (un jeton doté de policy:write, appartenant à un propriétaire de l’organisation) :

curl -sS -X POST "https://frem.sh/_app/api/v1/orgs/<org>/dependency-proxy/upstreams" \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"host": "docker.io", "auth_type": "basic", "username": "<docker-hub-user>", "password": "<docker-hub-token>"}'

La réponse contient l’id de l’identifiant et une empreinte, jamais le secret. Testez-le avec POST /orgs/<org>/dependency-proxy/upstreams/<id>/test, désactivez-le ou remplacez le secret avec PATCH /orgs/<org>/dependency-proxy/upstreams/<id>, et supprimez-le avec DELETE.

Le secret est en écriture seule : il est scellé lors de son enregistrement et n’est jamais renvoyé, journalisé ni écrit dans le journal d’audit. Le journal d’audit consigne qui a ajouté, modifié ou supprimé l’identifiant.

Récupérer via le proxy

Connectez-vous à frem.sh avec votre nom d’utilisateur fremforge et un jeton d’accès personnel disposant de read:package, puis récupérez avec le préfixe du proxy de dépendances :

docker login frem.sh -u <your-user>
docker pull frem.sh/<org>/dependency-proxy/docker.io/library/node:24-bookworm-slim

Les images officielles se trouvent sous library/ sur Docker Hub : node:24 devient donc frem.sh/<org>/dependency-proxy/docker.io/library/node:24. Les autres images conservent leur namespace : pgvector/pgvector:pg17 devient frem.sh/<org>/dependency-proxy/docker.io/pgvector/pgvector:pg17.

Vous pouvez aussi récupérer par digest, et un digest multiplateforme épinglé fonctionne sans modification :

FROM frem.sh/<org>/dependency-proxy/docker.io/library/node:24-bookworm-slim@sha256:<digest>

Dans Forgejo Actions

Une tâche peut se connecter avec son propre jeton de tâche. Elle passe uniquement par le proxy de dépendances de l’organisation de son propre dépôt.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: log in to the dependency proxy
        run: echo "${{ github.token }}" | docker login frem.sh -u "${{ github.actor }}" --password-stdin
      - run: docker build -t app .

Avec les lignes FROM du Dockerfile sur le préfixe frem.sh/<org>/dependency-proxy/docker.io/, le build récupère les images via le proxy avec cette connexion.

Une tâche déclenchée par une pull request provenant d’un fork ne s’exécute jamais avec les identifiants de votre organisation : elle ne peut donc pas récupérer d’images docker.io via le proxy. Récupérez-les directement depuis Docker Hub.

Sans identifiant

Si votre organisation n’a aucun identifiant docker.io activé, un pull via le proxy répond 403 DENIED :

docker.io needs your organisation's own Docker Hub credentials (decision D1): an organisation
owner adds them under Organisation settings > Dependency proxy > Upstream credentials

Le proxy ne se rabat pas sur un pull Docker Hub anonyme. Enregistrez un identifiant, ou référencez l’image directement (docker.io/...), ce qui constitue un pull anonyme soumis à la limite de Docker Hub pour les pulls anonymes.

Les autres registres se comportent différemment : ghcr.io et quay.io fonctionnent via le proxy de manière anonyme lorsque vous n’avez pas d’identifiant pour eux, et utilisent le vôtre lorsque vous en avez un.

Vérifier que cela fonctionne

• Récupérez une image via le proxy, puis consultez la page Usage de votre compte Docker Hub : le pull y est décompté, une seule fois. Un second pull de la même image est servi depuis le cache.
• Si un pull échoue avec 503 et your organisation’s docker.io credential could not be used, l’identifiant enregistré n’a pas pu être ouvert. Il s’agit d’une défaillance de fremforge, et elle est journalisée.