コンテンツへスキップ

GitHub ActionsでのDockerのPullレート制限:対処法

最終更新

toomanyrequests: You have reached your pull rate limit は、呼び出し元が上限に達したため Docker Hub が docker pull を拒否したことを意味します。CI では、多くの場合、共有 IP アドレスからの匿名 pull が原因です。対策は、ワークフローで Docker Hub にログインするか、自身で管理するミラーまたはレジストリから同じイメージを pull することです。以下の上限は Docker のpull の利用状況に関するドキュメントに基づき、2026年10月時点で確認したものです。

表示される正確なメッセージ

Error response from daemon: toomanyrequests: You have reached your pull rate limit.
You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits

BuildKit や docker/build-push-action の出力では、FROM の行や resolve image config のステップで 429 Too Many Requests として表示されます。文末の表現は Docker のバージョンによって異なりますが、HTTP 429 と toomanyrequests は共通です。

現在の上限

6時間ごとのウィンドウあたり:

呼び出し元Pull 数
認証なしIPv4 アドレスまたは IPv6 /64 サブネットあたり 100 回
認証済みの個人アカウントアカウントあたり 200 回
Pro、Team、Business無制限(公正利用の対象)

上限に達すると、Docker は HTTP 429 を返します。Docker は過去にこの数値を変更しているため、依存する前にページで最新の情報を確認してください。

CI で上限に達しやすい理由

  • 共有 IP。多数のお客様の多数のジョブが、同じ送信元アドレスを使うことがあります。匿名 pull は IP 単位で数えられるため、お客様側のわずかな pull が上限超過の決め手になることがあります。
  • 1回の実行での pull 数が多い。すべての FROM、サービスコンテナ、docker run が pull に該当します。3つのイメージを pull する20セルのマトリクスは、60回の pull になります。
  • ログインなし。認証情報がない場合、IP の匿名枠を共有することになります。
  • キャッシュのミス。ジョブごとに新しい VM を使うと、毎回イメージを pull し直すことになります。

対策(試す順)

1. Docker Hub にログインする

Docker Hub のアクセストークンを作成し(アカウント設定、その後 Personal access tokens)、シークレットとして保存したうえで、pull の前にログインします。

steps:
  - uses: docker/login-action@v3
    with:
      username: ${{ secrets.DOCKERHUB_USERNAME }}
      password: ${{ secrets.DOCKERHUB_TOKEN }}
  - uses: docker/setup-buildx-action@v3
  - uses: docker/build-push-action@v6
    with:
      context: .

これにより、アカウントの認証済み上限に切り替わります。レジストリのオプションについては docker/login-action の readme を参照してください。なお、フォークからのプルリクエストでトリガーされたワークフローではシークレットを利用できないため、それらの実行は引き続き匿名で pull します。

2. サービスコンテナを認証する

ジョブの services と container のブロックは、どのステップより前に pull を行うため、認証情報を直接指定してください。

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        credentials:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

3. 別のレジストリから pull する

多くの公式イメージは他の場所にもミラーされています。ベースイメージを GitHub Container Registry(GHCR)やお使いのクラウドのレジストリにコピーすると、パスから Docker Hub を外せます。GHCR のイメージは ghcr.io/OWNER/IMAGE で pull でき、ワークフローでは GITHUB_TOKEN を使ってログインできます。

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

スケジュール実行のワークフローで一度だけミラーする:

docker pull postgres:16
docker tag postgres:16 ghcr.io/OWNER/mirror/postgres:16
docker push ghcr.io/OWNER/mirror/postgres:16

ミラーするイメージのライセンス条件を確認してください。複数のクラウドが Docker Hub 公式イメージのパブリックミラーも提供しています。最新のアドレスはプロバイダーのドキュメントを参照してください。

4. Pull-through キャッシュを使う

Pull-through モードのレジストリ(Docker の registry イメージ、またはお使いのクラウドのレジストリ)は、Docker Hub から一度だけ取得し、以降はそれを配信します。デーモンがこれをミラーとして使うように設定してください。

sudo mkdir -p /etc/docker
echo '{"registry-mirrors": ["https://mirror.example.com"]}' | sudo tee /etc/docker/daemon.json
sudo systemctl restart docker

GitHub がホストするランナーでは、ジョブ内で Docker デーモンを再起動しても問題ありません。レジストリミラーのドキュメントを参照してください。

5. Pull の回数を減らす

  • ベースイメージをゼロから解決しないよう、BuildKit でレイヤーをキャッシュしてください(cache-from と cache-to)。CI での Docker レイヤーキャッシュを参照してください。
  • タグの参照を繰り返さないよう、イメージをダイジェストで固定してください。
  • 同じイメージを pull するジョブをまとめるか、ワークフローごとに1回だけイメージをアーティファクトとして保存してください。
  • 使わないイメージは pull しないでください。services ブロックを確認してください。

6. Docker のプランをアップグレードする

Pro、Team、Business のアカウントは、公正利用の範囲で無制限とされています。チームで大量に pull する場合、有料プランの方がエンジニアリングの工数より安く済むこともあります。

ランナーの選択とレート制限

レート制限は、ランナーの種類ではなく、アイデンティティまたは IP に依存します。専用マシンと、温まった Docker レイヤーキャッシュを持つランナープロバイダーでは、そもそも機械の外へ出る pull の回数が減ります。compiler.dev のマシン(8 vCPU / 16 GB、ジョブごとに新しい VM)は Docker レイヤーキャッシュを準備した状態で保持しており、runs-on: [self-hosted, Linux, compiler-ci] に切り替えて利用できます。それでも Docker Hub へのログインは行ってください。詳しくは料金をご覧ください。Docker イメージのビルド速度に特化するなら、Depot のような専用ビルダーも有力な選択肢です。比較ページをご覧ください。

予防方法

  1. ビルドとプルの前に、必ず docker/login-action を実行してください。
  2. services ブロックと container ブロックで認証を行ってください。
  3. 重要なベースイメージは、GHCR または独自のレジストリにミラーリングしてください。
  4. レイヤーをキャッシュし、ダイジェストを固定してください。
  5. CI で 429 エラーを検知するアラートを設定すると、リリースがブロックされる前に問題に気づけます。

GitHub 自体のレート制限エラーは別の問題です。API rate limit exceeded を参照してください。大きなイメージも No space left on device の一般的な原因です。

よくある質問

Docker Hub のプル制限とは何ですか?

認証されていないユーザーは 6 時間あたり 100 回まで (IPv4 アドレスまたは IPv6 /64 ごと)、認証された個人アカウントは 6 時間あたり 200 回までです。Pro、Team、Business は、公正な利用の範囲内で無制限です。

GitHub がホストするランナーには、Docker Hub の特別な制限がありますか?

そのような前提に頼らないでください。匿名のプルは制限されているものとして扱い、ログインしてください。

失敗したプルはカウントされますか?

Docker のドキュメントでは、制限はプル回数を基準に説明されています。429 を返したリクエストは成功したプルではありませんが、そのウィンドウ内で先に行われたプルはカウントされたままです。

GHCR にもレート制限はありますか?

GitHub Container Registry には独自のポリシーがあります。最新のルールについては、GitHub のドキュメントを確認してください。GHCR から公開イメージをプルしても、Docker Hub の制限は適用されません。