2026年5月以降、Maven Central が新しいレート制限を導入し、依存をダウンロードするビルドが HTTP 429（Too Many Requests）で失敗する事象が報告されています。Maven や Gradle、Leiningen を使う Java・Kotlin・Scala・Clojure のプロジェクトを CircleCI で運用している場合、依存取得のステップで突然ビルドが落ちる、あるいは取得が遅くなるといった影響を受けます。
CircleCI はこの問題に対して2系統の対策を提供しています。本記事では、そのうち広く利用できる「レジストリキャッシュ・プロキシ（registry cache and proxy）」を、実際に CircleCI 上で動かして確認した手順で紹介します。
本記事で使用する circleci experiment registry config は experimental（実験的）コマンドです。インターフェースは今後変更される可能性があります。本記事の内容は2026年6月時点のものです。
Maven Central の 429 と CircleCI の2系統の対策
今回の事象の発生源は、CircleCI ではなく Maven Central 側のレート制限です。Maven Central が一定時間あたりのリクエスト数に制限をかけたため、CI のように短時間で多数の依存を取得する環境が 429 を受けやすくなりました。レート制限の詳細は Sonatype 側の一次情報を参照してください。
これに対して CircleCI が用意している対策は2つあります。1つ目は IP Ranges 機能の利用者向けの対策で、CircleCI が Sonatype と連携し、CircleCI の専用 IP レンジを Maven Central のアクセス許可リストに追加しています。このため IP Ranges 機能を使っているジョブは、レート制限の影響を受けにくくなっています。2つ目が本記事で扱うレジストリキャッシュ・プロキシで、CircleCI が運用するプロキシ経由で Maven Central から依存を取得することで、Maven Central への直接リクエストを減らし、レート制限を回避します。こちらは IP Ranges を使っていない環境でも利用できます。
どちらに該当するかの判断は、次の表を目安にしてください。
| 状況 | 推奨される対策 |
|---|---|
| IP Ranges 機能を利用している | 追加対応は不要な場合が多い（allowlist 済み） |
| IP Ranges を利用していない | 本記事のレジストリキャッシュ・プロキシ |
| Maven / Gradle / Leiningen で依存取得している | 本記事のプロキシが適用対象 |
前提条件
本記事の手順は、以下を前提としています。
- CircleCI の Docker executor 上で Maven、Gradle、または Leiningen を使って依存を取得するジョブであること
- Java 環境のイメージ（例:
cimg/openjdk）を使用していること
特別なツールのインストールは不要です。cimg/openjdk イメージには Maven が含まれており、後述の circleci experiment registry config コマンドもジョブ実行環境内でそのまま利用できます。これは実際に cimg/openjdk のジョブ内でコマンドが動作することを確認しています。
circleci experiment registry config コマンドで設定する
このコマンドは、Maven Central への依存取得を CircleCI のプロキシ経由に切り替える設定を、ジョブ実行時に書き込みます。具体的には、Maven の設定ファイル ~/.m2/settings.xml に Maven Central をミラーするプロキシ設定を書き込み、認証用の環境変数 CIRCLECI_MAVEN_REGISTRY_ENDPOINT と CIRCLECI_REGISTRY_TOKEN を $BASH_ENV にエクスポートします。
対応するビルドツールはフラグで切り替えます。
| フラグ | 対象 | 書き込み先 |
|---|---|---|
--maven |
Maven | ~/.m2/settings.xml |
--gradle |
Gradle | Gradle の設定 |
--lein |
Leiningen | Leiningen の設定 |
--all |
上記すべて | 各設定ファイル |
--env |
設定ファイルを書かず、環境変数のみエクスポート | （ファイル書き込みなし） |
次の config.yml は、Maven プロジェクトで依存を取得する最小のジョブに、このコマンドを組み込んだ例です。ポイントは、circleci experiment registry config --maven を依存取得のステップより前に置くことです。プロキシ設定が書き込まれる前に依存を取得すると、Maven Central へ直接アクセスしてしまうためです。
version: 2.1
jobs:
build:
docker:
- image: cimg/openjdk:21.0
steps:
- checkout
- run:
name: Maven Central プロキシを設定 # 依存取得より前に実行する
command: circleci experiment registry config --maven
- run:
name: 依存を取得
command: mvn -B dependency:go-offline
workflows:
build:
jobs:
- build
上記の例では、circleci experiment registry config --maven のステップで ~/.m2/settings.xml が書き込まれ、続く mvn のステップがその設定を読み込んでプロキシ経由で依存を取得します。Gradle を使っている場合は --maven を --gradle に置き換え、依存取得コマンドを Gradle のもの（例: gradle dependencies）に変更してください。
実際にジョブで実行すると、コマンドは認証情報を settings.xml に書き込み、有効期限付きのトークンを発行したことをログに出力します。
ログの valid until が示すとおり、書き込まれるトークンには有効期限があり、ジョブごとに発行される短命のものです。
プロキシ経由になったことを確認する
設定が書き込まれただけでは、依存取得が実際にプロキシ経由になったとは限りません。ここでは、書き込まれた設定の中身、エクスポートされた環境変数、そして依存の取得元が切り替わったことを順に確認します。
書き込まれた settings.xml を確認する
circleci experiment registry config --maven の実行後に ~/.m2/settings.xml を表示すると、Maven Central（central）をミラーするプロキシ設定が書き込まれていることを確認できます。次は実際に書き込まれた内容から、認証情報を伏せたものです。
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
<servers>
<server>
<id>circleci-registry</id>
<username>aws</username>
<password>REDACTED（トークンが書き込まれる。ログ・スクショでは必ずマスクする）</password>
</server>
</servers>
<profiles>
<profile>
<id>circleci-registry</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<repositories>
<repository>
<id>circleci-registry</id>
<url>https://circleci-<account>.d.codeartifact.<region>.amazonaws.com/maven/maven-proxy/</url>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>circleci-registry</activeProfile>
</activeProfiles>
<mirrors>
<mirror>
<id>circleci-registry</id>
<name>circleci-registry</name>
<url>https://circleci-<account>.d.codeartifact.<region>.amazonaws.com/maven/maven-proxy/</url>
<mirrorOf>central</mirrorOf>
</mirror>
</mirrors>
</settings>
<mirrors> の <mirrorOf>central</mirrorOf> により、本来 Maven Central（central）へ向かうリクエストが、<url> で指定されたプロキシのエンドポイントへ振り向けられます。あわせて <profiles> と <activeProfiles> も書き込まれ、同じプロキシエンドポイントをリポジトリとして有効化します。このエンドポイントのホスト名から分かるとおり、CircleCI のレジストリキャッシュ・プロキシの実体は AWS CodeArtifact のリポジトリです。<username> は aws で固定され、<password> にはコマンドが発行した認証トークンが書き込まれます。エンドポイントのアカウントやリージョンの値は CircleCI 側で自動的に生成されるため、手動で設定する必要はありません。
settings.xml の <password> には有効な認証トークンが書き込まれます。このトークンは短命でジョブごとに発行されますが、ログやスクリーンショットを共有・公開する際は必ずマスクしてください。
エクスポートされた環境変数を確認する
コマンドは settings.xml の書き込みと同時に、CIRCLECI_MAVEN_REGISTRY_ENDPOINT と CIRCLECI_REGISTRY_TOKEN を $BASH_ENV にエクスポートします。$BASH_ENV に書き出されるため、これらの値は後続のステップでも参照できます。別のステップでエンドポイントとトークンの有無を確認すると、値が引き継がれていることが分かります。
ENDPOINT には CodeArtifact のプロキシエンドポイントが入り、TOKEN は値を出力せず設定済みであることだけを確認しています。トークンそのものはログに出さないよう、-n で存在確認のみを行っています。
依存の取得元が切り替わったことを確認する
最も分かりやすい確認方法は、mvn の出力にある Downloading from の行を見ることです。プロキシを設定する前と後で、取得元のホストが変わります。
設定前は、Maven Central（central）から直接ダウンロードしています。
circleci experiment registry config --maven を実行した後は、取得元が circleci-registry、すなわち CodeArtifact のプロキシエンドポイントに切り替わります。
取得元が central（repo.maven.apache.org）から circleci-registry（CodeArtifact のエンドポイント）へ変わっていれば、依存取得がプロキシ経由になっています。この Downloading from の差が、プロキシが効いていることの直接の証拠です。
注意事項
導入と運用にあたっての注意点を整理します。
- このコマンドは experimental です。将来インターフェースが変わる可能性があるため、
config.ymlに組み込む際は、CircleCI の更新情報を継続的に確認してください。CircleCI は今後、対応レジストリの拡充とこの設定の自動化を予定しています。 - IP Ranges 機能をすでに利用している場合は、Maven Central のアクセス許可リストに追加済みのため、本記事のプロキシ設定を追加しなくてもレート制限の影響を受けにくくなっています。両方を必ず併用する必要はありません。自分の環境がどちらに該当するかを確認した上で、必要な対策を選んでください。
- トークンを含む認証情報が
settings.xmlやログに出力されます。記事化やチーム共有で画面を見せる場合は、必ずマスクしてください。
まとめ
Maven Central の 429 に対しては、circleci experiment registry config --maven を依存取得ステップの前に1行追加することで、依存取得を CircleCI のプロキシ(実体は AWS CodeArtifact)経由に切り替えられます。IP Ranges 機能を使っていない環境でも適用でき、設定変更のコストは小さく済みます。
本記事では Maven を例に紹介しましたが、--gradle や --lein、複数をまとめて設定する --all も同じ仕組みで利用できます。設定ファイルを書かずに環境変数だけを使いたい場合は --env を指定してください。
詳細は以下を参照してください。
- 機能の更新情報: New: Registry cache and proxy for Maven Central
- 背景とレート制限の告知: CircleCI Discuss のアナウンス
- IP Ranges 機能: IP ranges のドキュメント