ビルドの再現性|同じ入力から同じ成果物を作る

ビルドの再現性|同じ入力から同じ成果物を作る

同じコミットを 2 回ビルドしたのに、できあがった成果物のハッシュ値が一致しないことがあります。

ソースは同じでも、ビルドした時刻やファイルの並び順、ビルドしたアカウントといった、意図していない情報が成果物に混ざるからです。

ビルドの再現性は、こうした混ざりものを取り除き、同じ入力からいつでも同じバイト列を作れる状態を指します。

定義と、ずれが入り込む経路、手元で確かめる方法が分かると、CI で「作り直しても同じか」を検査する意味にも説明がつきます。

私も DevOps を学んでいる途中なので、reproducible-builds.org や SLSA などの公開資料をもとに整理しました。

再現性はビット単位で同じことを求める

Reproducible Builds プロジェクトは、同じソースコード・ビルド環境・ビルド手順から、誰が作っても指定した成果物がビット単位で同じ複製になるとき、そのビルドを再現可能と定義しています。

ここでいうビルド環境には、依存ライブラリとそのバージョン、ビルドの設定フラグ、ビルドが読む環境変数(ロケールなど)が含まれます。

成果物は実行ファイルや配布パッケージ、ファイルシステムのイメージで、ビルドのログのような副産物はふつう含めません。

一致しているかは 1 ビットずつ比べて確かめるもので、実際には暗号学的ハッシュ関数を使って比べるのが一般的だと書かれていました。

どの属性を環境に含めるかは、再現できると主張する作者や配布元が決めることになっていて、その数は少ないほど望ましいとされています。

定義の原文は Definitions(reproducible-builds.org) です。

アーティファクトレジストリの記事では、一度ビルドしたものをビルドし直さずに各環境へ運ぶ考え方を扱いました。

そちらが「同じものを運ぶ」話なのに対して、再現性は「作り直しても同じものになる」話です。

アーティファクトレジストリ入門|ビルド成果物をどこに置くか

成果物を変えてしまう意図しない入力

Go チームの Russ Cox 氏は、出力を変えうる情報を「関係する入力」、そのうち意図せず入り込んだものを「意図しない入力」と呼んでいます。

いちばんよくある意図しない入力は、現在時刻です。

ビルドがファイルを書くとファイルシステムが更新時刻を記録し、それを tar や zip で固めると、その時刻がアーカイブに入ってしまいます。

同じ記事は、関係する入力の例として次のものを挙げていました。

  • ソースコードのバージョン
  • 組み込む依存ライブラリのバージョン
  • ビルドする OS(バイナリに入るパス名に影響する)
  • ビルドするマシンの CPU アーキテクチャ
  • コンパイラのバージョンとオプション
  • ソースを置いたディレクトリ名(デバッグ情報に入ることがある)
  • ビルドするアカウントのユーザー名・グループ名・uid・gid

Reproducible Builds プロジェクトの「戒律」の一覧には、ディレクトリの読み出し順、ハッシュ表の要素の順、並列処理の競合、タイムゾーン・ロケール・umask も入っています。

一覧は Commandments of reproducible builds で読めます。

Cox 氏は、関係する入力を文書に書き並べるだけでは再現の手間が大きすぎるとして、ソースコード以外の入力を取り除く方向を勧めています。

Go 1.21.0 はその取り組みの結果で、ソースコードだけが関係する入力になった最初の Go ツールチェーンだと説明されていました。

たとえばマップの反復順やゴルーチンの実行順から来るばらつきは、出力に使う前に並べ替えることで取り除いたと、Go 公式ブログの記事に書かれています。

tar と gzip で再現性を確かめる

時刻がどう混ざるかは、手元のシェルで確かめられます。

検証には、Windows 11 の Git for Windows 2.48.1 に同梱の bash 5.2.37、GNU tar 1.35、gzip 1.13、GNU coreutils 8.32 の sha256sum を使いました。

何もしないと時刻で変わる

次のスクリプトは、ビルドの代わりに dist/ を作り直して tar.gz に固めるだけのものです。

#!/usr/bin/env bash
# build.sh(ビルドの代わり)
set -eu
rm -rf dist && mkdir -p dist/bin
echo 'echo hello' > dist/bin/app.sh
echo 'version=1.0.0' > dist/VERSION
tar -czf "$1" dist

2 秒あけて 2 回実行すると、ハッシュ値は一致しませんでした。

$ ./build.sh out1.tar.gz; sleep 2; ./build.sh out2.tar.gz
$ sha256sum out1.tar.gz out2.tar.gz
1b1de4fea4ba6bf76f45ee76943f0de8b01b7979a8a71a23d0885248b04b8df3 *out1.tar.gz
d8386ea966f9f11bb397be3433a64655ffcc16fad70ae253efb45d60eccd54d6 *out2.tar.gz

中身の一覧を秒まで出して見比べると、違いは各ファイルに記録された更新時刻でした。

$ tar --full-time -tvzf out1.tar.gz | awk '{print $(NF-2), $(NF-1), $NF}'
2026-10-08 10:22:16 dist/
2026-10-08 10:22:16 dist/bin/
2026-10-08 10:22:16 dist/bin/app.sh
2026-10-08 10:22:16 dist/VERSION
$ tar --full-time -tvzf out2.tar.gz | awk '{print $(NF-2), $(NF-1), $NF}'
2026-10-08 10:22:19 dist/
# 略(4 行とも 10:22:19)

所有者の列には実行したアカウント名が出るので、awk で日時と名前だけに絞っています。

時刻と並び順と所有者を固定する

reproducible-builds.org の Archive metadata のページは、GNU tar で固めるときに時刻・並び順・所有者を固定するオプションを勧めています。

そこに権限の固定と gzip -n を足したのが次のスクリプトです。

#!/usr/bin/env bash
# build3.sh(dist/ を作る部分は build.sh と同じ)
set -eu
export LC_ALL=C
# 略
tar --sort=name \
    --mtime="@${SOURCE_DATE_EPOCH}" \
    --owner=0 --group=0 --numeric-owner \
    --mode=a=rX,u+w \
    --format=gnu \
    -cf - dist | gzip -n > "$1"

それぞれのオプションが消している入力は、次のとおりです。

オプション消している入力
–sort=nameディレクトリの読み出し順(GNU tar 1.28 以降)
–mtime各ファイルの更新時刻(全部を SOURCE_DATE_EPOCH にそろえる)
–owner / –group / –numeric-ownerビルドしたアカウントの名前と ID
–modeumask による権限の違い
–format=gnupax 形式で足される atime・ctime
gzip -ngzip のヘッダーに入る元の名前と時刻

出どころは Archive metadata(reproducible-builds.org) です。

SOURCE_DATE_EPOCH に 1767225600(2026-01-01 00:00:00 UTC)を入れて 2 回実行すると、ハッシュ値がそろいました。

$ export SOURCE_DATE_EPOCH=1767225600
$ ./build3.sh out3.tar.gz; sleep 2; ./build3.sh out4.tar.gz
$ sha256sum out3.tar.gz out4.tar.gz
5a1174fa68526208c99bf2426ae266b2236f3e210e33a9b8305c8f5aa9d77654 *out3.tar.gz
5a1174fa68526208c99bf2426ae266b2236f3e210e33a9b8305c8f5aa9d77654 *out4.tar.gz

別のディレクトリにスクリプトを置き、TZ=America/New_York を付けて実行したときも、ハッシュ値は同じ 5a1174fa… でした。

一覧を見ると、所有者は 0/0 になり、並びも C ロケールの名前順で VERSION が bin/ より先に来ています。

$ TZ=UTC tar --full-time -tvzf out3.tar.gz
drwxr-xr-x 0/0               0 2026-01-01 00:00:00 dist/
-rw-r--r-- 0/0              14 2026-01-01 00:00:00 dist/VERSION
drwxr-xr-x 0/0               0 2026-01-01 00:00:00 dist/bin/
-rw-r--r-- 0/0              11 2026-01-01 00:00:00 dist/bin/app.sh

umask の違いも成果物に出る

–mode を外した版を umask 077 の状態で実行すると、ハッシュ値は cdd5aaf7… に変わりました。

一覧では権限が rw——- で記録されていて、ビルドするユーザーの設定が成果物に漏れる例になっています。

–mode を付けた build3.sh なら、umask 077 で実行しても 5a1174fa… のままでした。

gzip のヘッダーにも名前と時刻が入る

gzip でファイルを直接圧縮すると、元のファイル名と更新時刻がヘッダーに記録されます。

中身が同じで更新時刻だけ違う 2 つの VERSION を圧縮すると、-n の有無で次の差が出ました。

$ gzip -c g1/VERSION | sha256sum
519d88de353048ec8a290fdefb632757e7573dc0d54d5f691c79203ca35e6154 *-
$ gzip -c g2/VERSION | sha256sum
1669971477c02ec5e44bb80040c8b9d94f8197393e0071ede72b5d442c309487 *-
$ gzip -nc g1/VERSION | sha256sum
388e0e8e72a5faaa508dbfa3f67a6e2dabb752aa808267df887ba65312d31648 *-
$ gzip -nc g2/VERSION | sha256sum
388e0e8e72a5faaa508dbfa3f67a6e2dabb752aa808267df887ba65312d31648 *-

なお、tar -czf のように標準入力から圧縮した最初の検証のファイルでは、ヘッダーの時刻欄は 0 でした。

CI では 2 回ビルドして比べる

再現性は、同じビルドを 2 回走らせてハッシュ値を比べる検査にすると、壊れたときにすぐ気づけます。

#!/usr/bin/env bash
# verify.sh(同じビルドを 2 回走らせて比べる)
set -eu
./"$1" first.tar.gz
sleep 2
./"$1" second.tar.gz
a=$(sha256sum < first.tar.gz)
b=$(sha256sum < second.tar.gz)
if [ "$a" = "$b" ]; then echo "reproducible: $a"; else echo "NOT reproducible"; exit 1; fi

build.sh を渡すと「NOT reproducible」で終了コード 1、build3.sh を渡すと「reproducible」で 0 が返りました。

ただし同じマシンで続けて 2 回ビルドしても、パスやアカウント、ロケールのようにマシンごとに決まる入力は変わりません。

その違いまで拾うには、別のディレクトリや別のマシン、別のコンテナで作り直して比べる必要があります。

ハッシュ値がずれたときに差分を探す道具としては、Reproducible Builds プロジェクトの diffoscope があります。

diffoscope はアーカイブを再帰的に展開し、バイナリを読める形に変換して比べるツールで、今回の環境には入っていないため実行していません。

紹介ページは diffoscope です。

壊れたビルドに早く気づく CI の考え方は、継続的インテグレーションの記事で整理しています。

継続的インテグレーション(CI)入門|壊れたらすぐ気づく

時刻と依存を固定する仕組み

手元の例では時刻を直接書きましたが、実際のビルドでは時刻と依存のバージョンを決める仕組みが用意されています。

SOURCE_DATE_EPOCH

SOURCE_DATE_EPOCH は、ビルドツールに「いまの時刻」の代わりに使う時刻を渡すための、標準化された環境変数です。

仕様では、値は 1970-01-01 00:00:00 UTC からの秒数で、ソースコードだけで決まり、ビルドのたびに同じ値になることが必須とされています。

値はソースの最終更新時刻にするのが推奨で、開発者なら最新コミットの日時を使う方法が例に挙がっていました。

それより新しい時刻を SOURCE_DATE_EPOCH まで巻き戻す「クランプ」も仕様に書かれていて、GNU tar の –clamp-mtime がその例として示されています。

仕様の原文は SOURCE_DATE_EPOCH specification です。

Docker の BuildKit もこの変数を読み、イメージのインデックスや設定、ファイルのメタデータの時刻を指定した値にそろえます。

Docker Docs には、GitHub Actions で最新コミットの時刻を渡す例が載っています(書式の提示で、手元では実行していません)。

# Docker Docs の例から抜粋
      - name: Get Git commit timestamps
        run: echo "TIMESTAMP=$(git log -1 --pretty=%ct)" >> $GITHUB_ENV
      - name: Build
        uses: docker/build-push-action@v7
        # 略
        env:
          SOURCE_DATE_EPOCH: ${{ env.TIMESTAMP }}

ページは Reproducible builds with GitHub Actions(Docker Docs) です。

NO IMAGE

依存はロックファイルで固める

依存ライブラリのバージョンも、ビルドのたびに解決し直すと日によって変わる入力になります。

npm の package-lock.json は、生成された依存の木を正確に記録し、途中で依存が更新されても後のインストールで同じ木を作れるようにするファイルです。

リポジトリにコミットして使う前提で、チームメンバーやデプロイ、CI がまったく同じ依存を入れられることが目的に挙げられていました。

説明は package-lock.json(npm Docs) にあります。

package-lock.json | npm Docs

CI で使う npm ci は、ロックファイルが package.json と食い違っていればロックファイルを書き換えずにエラーで止まります。

npm ci は package.json やロックファイルに書き込まないことも、npm-ci(npm Docs) に書かれていました。

npm-ci | npm Docs

先の「戒律」にも、取得先のサーバーが落ちたり中身が変わったりするので、オフラインでビルドできるようにしておく項目があります。

再現性に期待しすぎない

SLSA の FAQ は、「再現可能」と「検証済みの再現可能」を分けて説明しています。

再現可能は、同じ入力でビルドを繰り返すとビット単位で同じ出力になる性質のことです。

その利点として、デバッグのしやすさ、cherry-pick で出すリリースへの自信、ビルドキャッシュとストレージの効率、依存の正確な追跡が挙げられていました。

検証済みの再現可能は、2 つ以上の独立したビルド基盤で作った結果を突き合わせて、ビルドの来歴を裏付けるやり方を指します。

正しく設計すれば SLSA の Build レベルの要件を満たせる一方で、ソース・依存・配布の段階の脅威には効かないと明記されています。

作り直す側がみな同じパイプラインのソフトを使っていれば同じ攻撃に負けるので、独立していることも条件です。

再現が難しいビルドがあることや、クローズドソースでは独立した作り直し手を用意しにくいことも挙げたうえで、SLSA は検証済みの再現可能を直接は求めていません。

出典は Frequently asked questions(SLSA) です。

時刻を固定すると成果物からビルドした日時が読めなくなりますが、SOURCE_DATE_EPOCH の仕様は、作り直せる以上ビルドの日時はソフトの古さを示す指標として当てにならないとしています。

ソースの最終更新時刻のほうが、そのソフトの実際の古さを表すという考え方です。

最後に

ビルドの再現性は、同じソース・環境・手順から、ビット単位で同じ成果物を作れる状態のことでした。

ずれの原因の多くは時刻・並び順・所有者・権限・依存のバージョンといった意図しない入力で、tar と gzip ならオプションを数個足すだけで手元でも取り除けました。

再現性は配布物の改ざんを見つける手がかりになりますが、ソースや依存そのものの安全までは保証しません。

まずは CI で同じビルドを 2 回走らせ、ハッシュ値を比べるところから始められます。

以上です。

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

CAPTCHA