島田則幸

証跡の残し方

かんたんに言うと 証跡とは「いつ、どの環境で、どのコマンドを実行し、どんな結果になったか」を後から確認できる形で残した記録です。自分以外の人が読んでも同じことを再現できる状態にしておくのが目的です。

ディレクトリ

infra-evidence/
├── measured/       # 実測（自分で動かして測った記録）。日時・コミット・環境・コマンド・結果は必ず書く
├── ci-generated/   # CI（変更のたびに自動で検査を実行する仕組み）が作った成果物への索引、または取得した結果
└── samples/        # 架空例。ファイル名にsampleを付ける

実測の必須項目

かんたんに言うと 「同じ条件でやり直せば同じ結果になるはずだ」と第三者が判断できるだけの情報をそろえます。実測の記録には、次の9項目を必ず書きます。

UTC（世界共通の基準時刻。時差がない）での開始日時と終了日時
Git のコミット SHA（そのコミットを一つに特定するID）と、dirty 状態（コミットしていない変更が残っているかどうか）
OS、カーネル（OSの中核部分）、CPU、メモリ、ディスク、仮想化方式
使ったツールの版（バージョン）
実行したコマンドと、そのとき期待していた結果
stdout（画面へ出る通常の出力）/ stderr（エラー時の出力）、exit code（コマンドの終了コード。0なら成功）、合否
秘密情報（パスワード、鍵、Token など）を取り除いたことを確認した人の名前
残っている課題と、もう一度試験をやり直すときの条件
各ファイルの SHA-256（ファイルの中身から計算する指紋のような値。中身が変わっていないか後から確かめられる）

bash scripts/capture-lab-evidence.sh <label> -- <command...> を実行すると、証跡をまとめて保存できます。保存されるのは、メタデータ（実行した日時や環境などの付帯情報）、実行したコマンド、stdout、stderr、exit code、checksum（SHA-256 などの検査用の値）で、これらは同じディレクトリに入ります。保存したあとは、必ず自分の目で中身を読みます。IP アドレス、ユーザー名、Token などを公開してよいかどうかを確認するためです。scripts/check-secrets.jsによるCI検査は、Git の追跡対象になっているファイル（Git が変更を管理しているファイル）の中身を調べます。パスワードや鍵などの credential（認証情報）でよく使われるパターンを見つけると、そこで処理を止めます。ただし、見つけた内容を伏せ字にしたり削除したりはしません。また、まだ Git の追跡対象になっていないファイルは検査の対象外です。ですから、この自動検出だけを信用せず、必ず自分の目でも確認します。

昇格条件

かんたんに言うと 記録の区分（SAMPLE / NOT RUN / MEASURED）を、実態より良く見せる方向へ書き換えないための決まりです。区分を上げてよいのは、実際にやり直して証拠がそろったときだけです。

SAMPLE（架空例）をMEASURED（実測済み）へ名前変更してはいけない。実際に再実行して新規採録する。
CI結果は本人PCの実績と表現しない。自動実行の結果は、自分の手元の機材で動かした証拠ではないためである。
NOT RUN（未実施）は、日時・環境・結果がそろった場合だけMEASUREDへ変更する。
過去結果と現行mainの状態を分ける。過去に測った結果が、いまのmainブランチ（公開している最新の状態）でも同じとは限らないためである。

This site is open source. Improve this page.