公開 API キーで、オープンソースのビルドを誰でも再現できるようにする
StableBuild の API キーは、通常は非公開で使うものです。社内のビルドならそれで困りませんが、オープンソースプロジェクトとなると話は別です。
Dockerfile やビルド設定は公開できても、リポジトリをクローンした人が StableBuild 経由で同じバージョンのパッケージやキャッシュ済みのコンテナを取得するには、認証情報が必要になります。
そこで用意したのが公開 API キーです。プロジェクトと一緒に配布することを前提にしたキーで、リポジトリにそのままコミットできます。ビルドが StableBuild 経由で取得する依存関係をあらかじめ記録しておけば、誰でも同じ依存関係を取得できます。組織の StableBuild キャッシュにあるほかの依存関係まで公開されることはありません。
依存関係を記録する仕組み
公開 API キーは、作成した時点では読み取り専用です。取得できるのは、キーの許可リストに登録され、かつ StableBuild にキャッシュ済みの依存関係だけです。
許可リストを作るには、キーの書き込み期間を開始してから、ビルドを一度実行します。書き込み期間中、キーは通常の StableBuild API キーと同じように使え、そのビルドで StableBuild 経由で取得した依存関係がすべて許可リストに追加されます。ビルドが終わったら、書き込み期間を終了します。
これで、公開 API キーを使う人は記録済みの依存関係を取得できるようになります。ただし、このキーで組織の StableBuild アカウントを経由して、新しいパッケージやコンテナ、ファイルを取得することはできません。
StableBuild が Dockerfile を解析したり、依存関係グラフを推測したりすることはありません。記録されるのは、書き込み期間中にビルドが実際に StableBuild に要求したものだけです。
ビルド全体で使える1つのキー
公開 API キーは、StableBuild の各ミラーで共通して使えます。たとえば、ベースイメージ、Debian パッケージ、Python の依存関係、URL からダウンロードするファイルをすべて StableBuild 経由で取得する Dockerfile は、次のようになります。
FROM your-prefix-pub-myproject.dockermirror.stablebuild.com/python:3.12-slim
ARG SB_API_KEY=your-prefix-pub-myproject
ARG APT_PIN_DATE=2026-09-29T08:40:01Z
COPY ./sb-apt.sh /opt/sb-apt.sh
RUN bash /opt/sb-apt.sh load-apt-sources debian
RUN apt update && apt install -y curl
RUN pip install \
-i https://your-prefix-pub-myproject.pypimirror.stablebuild.com/2026-09-01/ \
requests==2.32.3
RUN curl -O \
"https://your-prefix-pub-myproject.httpcache.stablebuild.com/my-cache-key/https://bootstrap.pypa.io/get-pip.py"
書き込み期間中にこのビルドを実行すると、各サービスを通じて取得した依存関係がすべてキーに記録されます。書き込み期間を終了した後は、記録された依存関係しか取得できません。
つまり、リポジトリをクローンした人は、メンテナから非公開の API キーを受け取らなくても、同じビルドを実行できるわけです。プロジェクトと関係のないキャッシュ済みの依存関係は、非公開のままです。
許可リストの更新
依存関係は、いずれ変わるものです。プロジェクトを更新して新しい依存関係が必要になったら、もう一度書き込み期間を開始し、更新後のビルドを実行してから終了します。新たに取得した依存関係が、キーの許可リストに追加されます。
許可リストは StableBuild のダッシュボードからも確認でき、公開する必要がなくなった項目を個別に削除できます。
書き込み期間は、1時間後、24時間後、7日後のいずれかに自動で終了するよう設定できます。それでも、ビルドが終わったらすぐに終了することをおすすめします。書き込み期間中は、公開 API キーを知っている人なら誰でも、新しい依存関係を取得できてしまうからです。
再現可能なビルドと依存関係へのアクセス
Reproducible Builds プロジェクトは、同じソースコード、ビルド環境、ビルド手順から、ビット単位で同一の成果物を作り直せることを「再現可能なビルド」と定義しています。そして、ビルド環境には通常、依存関係とそのバージョンも含まれるとしています。
オープンソースプロジェクトの場合、ビルドし直す人がそうした依存関係を実際に取得できなければ意味がありません。Dockerfile でパッケージのバージョンや使うコンテナを固定していても、公開されたビルド設定が非公開の API キーで StableBuild を参照していれば、コントリビューターは認証情報なしでは依存関係を取得できません。
公開 API キーを使えば、依存関係へのアクセス手段をビルド設定と一緒にプロジェクトに含められます。コントリビューターや下流の利用者は、組織の非公開キーやほかのキャッシュ済み依存関係へのアクセス権を渡されなくても、そのプロジェクト用に記録された依存関係を取得できます。
もちろん、公開 API キーだけでビルドが完全に再現可能になるわけではありません。タイムスタンプや環境の違いなど、StableBuild の外にもビルド結果を左右する要素はたくさんあります。公開 API キーの役割は、もっと限られています。StableBuild で保持している依存関係を、プロジェクトをビルドし直したい人も取得できるようにすることです。
利用量の計上と確認方法
公開 API キー経由のトラフィックは、キーを作成した組織の利用量として計上されます。Community プランでも、公開 API キーを使ったビルドのトラフィックは組織の月間トラフィック枠から消費され、通常の上限が適用されます。
トラフィックは、ダッシュボードの「請求 > 生の使用ログ」で確認できます。リクエストごとに使われた API キーが表示されるので、プロジェクトと一緒に公開したキーがどのように使われているかも把握できます。
オープンソースプロジェクトを運営していて、コントリビューターにもピン止めした依存関係でビルドしてもらいたい場合は、StableBuild アカウントを作成して公開 API キーを追加し、書き込み期間中にビルドを一度実行してみてください。これでプロジェクトの依存関係が記録されます。
詳しい設定手順は、公開 API キーのドキュメントをご覧ください。
