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 のような専用ビルダーも有力な選択肢です。比較ページをご覧ください。
予防方法
- ビルドとプルの前に、必ず
docker/login-actionを実行してください。 servicesブロックとcontainerブロックで認証を行ってください。- 重要なベースイメージは、GHCR または独自のレジストリにミラーリングしてください。
- レイヤーをキャッシュし、ダイジェストを固定してください。
- 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 の制限は適用されません。
関連記事
- CIでDockerビルドが遅い?原因を特定して解決CIでDockerビルドが遅いですか?ビルドコンテキストのサイズ、.dockerignore、レイヤーの順序、キャッシュミス、BuildKitの設定を診断し、最も影響の大きい問題から修正しましょう。
- Buildxを使ったCIでのDockerレイヤーキャッシュcache-fromとcache-to、ghaおよびregistryバックエンド、キャッシュヒットを狙った順序のDockerfileを使い、GitHub ActionsでのDockerビルドを高速化しましょう。
- GitHub Actionsでの API レート制限超過: 対処法GitHub Actionsで「API rate limit exceeded for installation ID」を解決します。GITHUB_TOKENはリポジトリごとに1時間あたり1,000リクエストまで。セカンダリ制限と対処法を解説します。
- DockerビルドのGitHub ActionsワークフローテンプレートBuildx、GitHubのキャッシュレイヤー、mainへのプッシュ時のGHCRへのプッシュを使ってDockerイメージをビルドする、最小限の権限で動作するGitHub Actionsワークフローのコピー&ペースト用サンプルです。