CI におけるガバナンス
読了まで約77 分分、14 節 節の 10 例 例。
この章を終えると、2章から7章までのガバナンスチェックを、プルリクエストごとに1つのジョブとして実行できるようになる。ジョブはプルリクエストが変更する部分だけを判定する。列に分類がなければ失敗し、アクセスポリシーと強制層のテストを実行し、各スキーマ変更が下流のどこに及ぶかを報告する。さらに、破壊的変更チェッカー(スキーマの2つのバージョンを比較して、読み手を壊す変更を見つけるツール)が扱わない2つのルールを強制する。所有者の情報は、メタデータから生成した Open Data Contract Standard(ODCS)の契約に持たせ、ドメインごとにフォルダとコードオーナーを置く。各ドメインのルールはグローバルなルールの上に重ね、各チェックのノイズは、誰も対応しない指摘の数で測る。
前の章では、チームが毎週スキーマを変更するオンライン学習プラットフォームのガバナンスチェックを構築した。しかし、どのプルリクエストもそれらを実行しない。2章ではレビュー済みのメタデータに対してカタログをテストし、4章ではパイプラインの実行ごとにリネージを読み取る。5章ではアクセスポリシーをテストし、6章ではそれをクエリに強制する層をテストする。7章では分類からテーブルプロパティを生成する。各チェックは、誰かがその例を実行したときにしか動かず、チームがプラットフォームを変更したときには動かない。ここに3つの変更が控えている。CRM チームは学習者の勤務先メールアドレスの列を追加したい。学習チームはレポーティングパイプラインが読む列の名前を変更したい。データサイエンスチームは学習者の居住都市をマスクなしで見たい。どれもレビュアーが承認しそうな小さな差分だが、どれも、何が壊れるか、あるいは誰が何を見るかを変える。
この章では、これらを検出するための、本書で共有するモジュール lib.ci を追加する。これはプラットフォームのガバナンスジョブである。この章でいうジョブは、この CI ジョブのことであり、OpenLineage のジョブではない。模擬のプルリクエストはそれぞれオフラインで実行され、チェックアウトと呼ぶ2つのフォルダ、すなわち main ブランチのものとプルリクエストのブランチのものを使う。各フォルダには次のものが入っている。governance/ はプラットフォームのガバナンスファイル、pipelines/ はパイプラインの SQL、migrations/ はブランチがスキーマを変更するための alter table 文であり、lib.ci.migrate がこれを Iceberg のスキーマ変更として適用する。そしてメタデータから生成されたファイルである。lib.ci.build は、各側について、プラットフォームの実際の動かし方に沿って作業用のプラットフォームを構築する。ソーステーブル、その側のマイグレーション、デプロイ(メタデータをカタログに書き込み、各テーブルの生成プロパティを設定する)を行い、続いてその側のパイプラインを夜間実行して、リネージを記録する。これらのパイプラインのうち review_corpus は4章のガバナンス対象外のコピーのままであり、ジョブはそのリネージを引き続きチェックする。プラットフォームは9章のガバナンス済みビルドで学習する。lib.ci.run はチェックを実行し、両側を比較する。git もネットワークも使わず、日付はすべて、時計ではなく本書の「今日」である 2026年10月1日と比較する。
この部分はまだ翻訳されていないため、英語で表示している。
Run every check as one job
A check that runs when someone remembers it is a report, and reports go unread. On a pull request, a check is a gate: it runs on every change, before the change merges, and it fails the pull request through its exit code. That is how Open Policy Agent (OPA) advises running policies in CI, with flags, --fail and --fail-defined, that set the exit code to 1 based on query results (OPA CI/CD docs). A job made of several checks needs four things more:
- Every check runs and reports all its findings, so one failure doesn't hide the next. A check that crashes becomes one finding, "the check could not run", which fails the job while the other checks run.
- Every finding has a stable ID, so the same problem has the same name on every run and can be discussed, counted and waived.
lib.ciwrites it as the check and the subject, such ascoverage/crm.learners.work_email. - The job judges what the pull request changes. It runs the main branch's checks too, and compares the two. A finding the pull request introduces fails it. A finding already on main is reported on every run, counted and named with the team that owns it, but it fails no pull request that leaves it as it is. We judge that a check that fails every pull request for findings nobody in it caused gets switched off. Google's code-analysis platform, Tricorder, shows most of its analyses' results only on the lines a change touches, by default (Sadowski et al., 2015).
- The list of checks lives in a reviewed file,
governance/ci.toml, so switching one off is a diff that someone approves.
The platform's job runs these checks, in this order:
| Check | From | Fails when |
|---|---|---|
coverage |
Chapters 2 and 3 | A table has no metadata or owner, or a column no classification or one below its name's suggestion |
contract-rules |
This chapter | A contract breaks a global or a domain rule |
contracts |
This chapter | A generated file is out of date |
policy-tests |
Chapter 5 | A Rego test or a who-sees-what row fails |
enforcement-tests |
Chapter 6 | A regression case or a who-sees-what query fails |
migrations |
This chapter | Iceberg refuses a migration |
pipelines |
Chapter 4 | A pipeline can't run, or its lineage can't be read |
lineage-classifications |
Chapter 4 | A column is declared less protected than lineage proposes |
owner-review |
This chapter | A classification drops, or an owner or domain changes, unapproved |
removals |
This chapter | A column is removed before it was deprecated |
properties |
Chapter 7 | A table lacks the properties generated for it |
The first pull request the job sees is the CRM team's. Employers buy team licences for their staff, so the team adds work_email to crm.learners in one migration, and forgets the column's metadata:
1"""The platform's governance job on one pull request, run as a CI step runs it: the CRM team adds a work email to2crm.learners. The prose's point rests on the coverage finding for the new column and on the exit code the step returns."""34from lib import ci5from lib.platform import scratch67main = ci.checkout() # the main branch: governance files, pipelines and the files generated from them8branch = ci.checkout(main) # the pull request's branch, starting from main9(branch / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")10print("files the pull request changes:", ", ".join(ci.changed(main, branch)))1112# What a CI step runs, `python -m lib.ci MAIN BRANCH --summary FILE`: it prints the report and its totals, writes the13# report as Markdown for the pull request, and exits with the code it returns.14summary = scratch() / "summary.md"15code = ci.main([str(main), str(branch), "--summary", str(summary)]) # 1 when a finding this pull request adds fails it16print("the step exits with:", code)17print("the summary it writes for the pull request:")18print(summary.read_text(encoding="utf-8"), end="")
python governance-ci-report.pyfiles the pull request changes: migrations/0001-add-work-email.sql
coverage: failed, findings 3, new 1, on main 2, waived 0, 12 tables checked
contract-rules: passed, findings 0, new 0, on main 0, waived 0, 10 contracts checked
contracts: passed, findings 0, new 0, on main 0, waived 0, 11 files checked
policy-tests: passed, findings 0, new 0, on main 0, waived 0, 24 tests and rows checked
enforcement-tests: passed, findings 0, new 0, on main 0, waived 0, 44 cases checked
migrations: passed, findings 0, new 0, on main 0, waived 0, 1 migrations checked
pipelines: passed, findings 0, new 0, on main 0, waived 0, 4 pipelines checked
lineage-classifications: passed, findings 0, new 0, on main 0, waived 0, 23 columns checked
owner-review: passed, findings 0, new 0, on main 0, waived 0, 77 columns checked
removals: passed, findings 0, new 0, on main 0, waived 0, 87 columns checked
properties: passed, findings 4, new 0, on main 4, waived 0, 12 tables checked
coverage/ai.review_corpus: no metadata; on main, owner team-platform
coverage/crm.learners.work_email: not classified; its name suggests personal
coverage/marketing.audience: no metadata; on main, owner team-platform
properties/ai.review_corpus: 7 of 7 generated properties missing; on main, owner team-platform
properties/analytics.course_performance: 4 of 4 generated properties missing; on main, owner team-analytics
properties/analytics.learner_activity: 4 of 4 generated properties missing; on main, owner team-analytics
properties/marketing.audience: 7 of 7 generated properties missing; on main, owner team-platform
change crm.learners, field 16: added as work_email string; named by 0 pipelines, reaches 0 columns
job: failed
checks run: 11
checks failed: 1
findings: 7
findings the pull request introduces: 1
findings already on main: 6
findings waived: 0
findings approved: 0
exit code: 1
the step exits with: 1
the summary it writes for the pull request:
## Governance job: failed
| Check | Result | New | On main | Waived | Checked |
| --- | --- | ---: | ---: | ---: | --- |
| `coverage` | failed | 1 | 2 | 0 | 12 tables |
| `contract-rules` | passed | 0 | 0 | 0 | 10 contracts |
| `contracts` | passed | 0 | 0 | 0 | 11 files |
| `policy-tests` | passed | 0 | 0 | 0 | 24 tests and rows |
| `enforcement-tests` | passed | 0 | 0 | 0 | 44 cases |
| `migrations` | passed | 0 | 0 | 0 | 1 migrations |
| `pipelines` | passed | 0 | 0 | 0 | 4 pipelines |
| `lineage-classifications` | passed | 0 | 0 | 0 | 23 columns |
| `owner-review` | passed | 0 | 0 | 0 | 77 columns |
| `removals` | passed | 0 | 0 | 0 | 87 columns |
| `properties` | passed | 0 | 4 | 0 | 12 tables |
### To fix in this pull request
- `coverage/crm.learners.work_email`: not classified; its name suggests personal
### Already on main, and whose it is
- `coverage/ai.review_corpus`: no metadata (team-platform)
- `coverage/marketing.audience`: no metadata (team-platform)
- `properties/ai.review_corpus`: 7 of 7 generated properties missing (team-platform)
- `properties/analytics.course_performance`: 4 of 4 generated properties missing (team-analytics)
- `properties/analytics.learner_activity`: 4 of 4 generated properties missing (team-analytics)
- `properties/marketing.audience`: 7 of 7 generated properties missing (team-platform)
### Schema changes
- `crm.learners`, field 16: added as work_email string; named by 0 pipelines, reaches 0 columns
The pull request introduces 1 finding, and it is the one that fails the job: crm.learners.work_email is not classified; its name suggests personal. The suggestion comes from chapter 3's name rules, which match e_?mail, so the finding says what to add. Of the job's checks, 1 fails, and the step exits with code 1. The coverage findings on main are marketing.audience and ai.review_corpus, the tables nobody has described since chapter 2 found them. Neither table has an owner, so the job names the platform team, which ci.toml makes answerable for tables nobody owns. Chapter 4's lineage shows that both hold personal data, and every report repeats them until someone describes them.
The other checks pass, among them chapter 5's policy tests, run on the data the branch's files generate, and chapter 6's enforcement tests, run on the branch's tables. The properties check reports findings on main, such as 4 of 4 generated properties missing; on main, owner team-analytics: the tables pipelines write lose their generated properties on every nightly run, as chapter 7 found, on main as on the branch. The schema change, added as work_email string; named by 0 pipelines, reaches 0 columns, reaches nothing yet.
Working rule: Run every check as one job on every pull request, each reporting all its findings under stable IDs, and a crashed check as a failing finding. Fail the job by exit code on any finding the pull request introduces that is neither waived nor approved. Report every finding already on main, counted and named with its owner, without failing a pull request that leaves it as it is. Keep the list of checks in a reviewed file.
コミットではなくプルリクエストをゲートにする
プラットフォームのジョブは CI 上で実行される。チェックを実行できる場所はもう一つあり、作成者のマシン上で、コミットが作られる前に動く pre-commit フックである。git フックのフレームワークである pre-commit は、通常、コミットが変更するファイルに対してのみフックを実行する。そのドキュメントは、フックをコードレビューの前に単純な問題を見つける手段として位置づけている(pre-commit)。これは、1 つのファイルだけで足りるチェックに向いている。たとえば、metadata.toml が構文として正しく解析できること、およびすべての分類が 4 つの値のいずれかであることである。
しかし、カバレッジのチェックには向かない。CRM チームのプルリクエストは migrations/0001-add-work-email.sql を変更しただけで、メタデータファイルは変更していなかった。そのため、メタデータファイルに絞り込んだフックには、チェックする対象が何もなかったはずである。欠落は、移行によって変更されたカタログと、プルリクエストが一度も触れなかったファイルとの間にあり、カタログ全体を構築するジョブだけがそれを検出できる。pre-commit の always_run を使えば、一致するファイルがなくてもフックを実行するよう設定できる。ただし、フックが動くのは誰かがインストールした環境だけである。また、pre-commit の SKIP 変数や git の --no-verify によって、誰でもフックを省略でき、レビュー担当者はどちらも確認できない。
したがって、ゲートはプルリクエスト上のジョブであり、それを必須にする。GitHub のブランチ保護では、保護されたブランチへ共同作業者が変更をマージする前に、必須のステータスチェックがすべて成功することを要求できる(GitHub, protected branches)。必須でないステータスは助言にすぎない。指摘がどこに表示されるかも、同じくらい重要である。Google の Tricorder の作者らは、開発者がダッシュボードを開いたり別のコマンドラインツールを実行したりする必要がある場合、解析の利用が減ることを見いだした(Sadowski et al., 2015)。これは一企業のコード解析の事例であり、データの事例ではないが、lib.ci.main が終了コードを返すだけにとどまらない理由である。CI のステップは python -m lib.ci MAIN BRANCH としてこれを実行し、指摘ごとに 1 行、その ID と追加すべき内容を出力する。また、レポートを Markdown として書き出し、レビュー担当者が差分を読むプルリクエストに載せる。サマリーの投稿と、プルリクエストのレビューからの承認の読み取りは、CI サービスの役割であり、本書の範囲外である。
実践ルール: フックは、作成者のマシン上での単一ファイルに対する高速なチェックに使い、プルリクエスト上の CI ジョブをゲートとして、メインブランチのブランチ保護で必須にする。すべての指摘は、その ID と対処方法を添えて、ダッシュボードだけでなくプルリクエスト自体に載せる。プルリクエストを経ずに変更されるテーブルのために、そのチェックを本番カタログに対しても定期的に実行する。
スキーマ変更の影響範囲を報告する
CRM チームが追加した列は下流の何にも影響しなかったが、名前の変更は影響する。しかも、Iceberg、SQL、ガバナンスメタデータという 3 種類の読み手は、それぞれ異なる判断を下す。Iceberg の読み手はフィールド ID で列を見つける。仕様には「projection must be done using field ids」とあり(Iceberg table spec, 1.12.0)、名前を変更した列でも、変更前に書かれたすべてのファイルを読める。SQL は名前で列を見つけるので、同じ名前変更によって、その列の名前を指定するすべてのクエリとパイプラインが壊れる。プラットフォームのガバナンスメタデータは、2 章で決めたとおりフィールド ID をキーにしているので、名前の変更では ID の隣にある名前を更新するだけでよい。仕様で有効なプリミティブ型の昇格は、int から long、float から double、そして精度の拡大のみが許される decimal の精度である。フォーマット v3 では、これに加えて date から timestamp または timestamp_ns への昇格と、型が unknown の列から任意の型への変更が有効である。これら以外の変更は、新しい列を意味する。
変更がどの SQL を壊すかは系譜の問題であり、4 章ではカラムグラフをたどることで答えた。レビューでは INDIRECT エッジもたどる必要がある。これは 4 章での呼び名で、出力の値そのものではなく、出力がどの行を保持するかを決める入力を指す。OpenLineage の列系譜ファセットは、フィルタリング、ソート、グループ化、結合、ウィンドウ関数などを通じてデータセット全体に影響する列系譜のために、dataset のリストを保持する(ColumnLineageDatasetFacet, 1.54.0)。結合やグループ化にだけ使われる列は、それが入力となるすべての行の形を決めるが、値のコピーだけを見る報告ではこれを見落とす。lib.ci.changes は、両側のスキーマをフィールド ID ごとに比較する。ブランチで名前の変更、型の変更、削除が行われた列ごとに、main ブランチの系譜グラフをたどる。対象は、SQL がその列の名前を指定するパイプライン、値がその列に由来する列、その列が変更しうるすべての列、そしてそれらを所有するチームである。
次は、学習チームによる learning.courses.category から subject への名前変更である。変更はマイグレーションとメタデータファイルの両方で行われる。同じプルリクエストで、この列の名前を指定する 2 つのパイプラインも修正される。
1"""What the learning team's rename of learning.courses.category reaches, through Iceberg readers, SQL and lineage. The2prose's point rests on the courses an Iceberg reader still finds, the columns reached, and the job's verdict once the fix merges with the rename."""3import pyarrow.compute as pc45from lib import ci, retention67main = ci.checkout()8branch = ci.checkout(main)9(branch / "migrations" / "0001-rename-category.sql").write_text(10 "alter table learning.courses rename column category to subject;\n")11ci.edit(branch, "governance/metadata.toml", '3 = { name = "category", classification = "public"',12 '3 = { name = "subject", classification = "public"') # the same field ID, renamed1314before, after = ci.build(main), ci.build(branch)15# matched by field ID, so the rename is one change, not a column dropped and another added16change = next(c for c in ci.changes(before, after) if c.table == "learning.courses")17print("change:", change.kind, "from", change.before, "to", change.after)18print("field ID, before and after:", change.field_id)19# read by the new name: Iceberg maps it to the same field ID as before20subjects = after.catalog.load_table("learning.courses").scan(selected_fields=("subject",)).to_arrow()21print("courses whose subject an Iceberg reader finds:", pc.count(subjects["subject"]).as_py())22print("pipelines whose SQL names it:", ", ".join(change.jobs))23for job, why in sorted(after.failed.items()):24 print(f"pipeline {job}, on the branch:", why)25print("columns whose values come from it:", len(change.values))26for column in change.values:27 print(" value of:", column)28print("columns it can change, DIRECT and INDIRECT:", len(change.reached))29# a column's table is the first two parts of its name, schema.table.column30print("tables those columns are in:", ", ".join(sorted({".".join(c.split(".")[:2]) for c in change.reached})))31print("owners the report goes to:", ", ".join(change.owners))32print("tables on main:", len(retention.tables(before.catalog)))33print("tables on the branch:", len(retention.tables(after.catalog)))34coverage = ci.run(before, after, checks=["coverage"]).checks[0]35print("coverage findings on the branch:", ", ".join(finding.id for finding in coverage.findings))3637# The same pull request, with both pipelines changed to read the new name. Each side runs its own pipelines/.38ci.edit(branch, "pipelines/course_performance.sql", " c.category,", " c.subject as category,")39ci.edit(branch, "pipelines/course_performance.sql", "c.title, c.category", "c.title, c.subject")40sql = (branch / "pipelines" / "marketing_audience.sql").read_text(encoding="utf-8")41(branch / "pipelines" / "marketing_audience.sql").write_text(sql.replace("c.category", "c.subject").replace(42 "f.category", "f.subject"), encoding="utf-8")43fixed = ci.build(branch)44ci.generate(fixed) # and the contracts generated again, as the author's hook would45print("files the fixed pull request changes:", ", ".join(ci.changed(main, branch)))46for line in ci.lines(ci.run(before, fixed, checks=["pipelines", "coverage", "contracts", "lineage-classifications"])):47 print("with the fix,", line)
python schema-change-impact.pychange: renamed from category string to subject string
field ID, before and after: 3
courses whose subject an Iceberg reader finds: 200
pipelines whose SQL names it: course_performance, marketing_audience
pipeline course_performance, on the branch: Unknown column: category
pipeline marketing_audience, on the branch: Unknown column: category
columns whose values come from it: 2
value of: analytics.course_performance.category
value of: marketing.audience.favourite_category
columns it can change, DIRECT and INDIRECT: 12
tables those columns are in: analytics.course_performance, marketing.audience
owners the report goes to: no owner, team-analytics
tables on main: 12
tables on the branch: 10
coverage findings on the branch: coverage/ai.review_corpus
files the fixed pull request changes: governance/contracts/learning/courses.odcs.yaml, governance/metadata.toml, migrations/0001-rename-category.sql, pipelines/course_performance.sql, pipelines/marketing_audience.sql
with the fix, pipelines: passed, findings 0, new 0, on main 0, waived 0, 4 pipelines checked
with the fix, coverage: passed, findings 2, new 0, on main 2, waived 0, 12 tables checked
with the fix, contracts: passed, findings 0, new 0, on main 0, waived 0, 11 files checked
with the fix, lineage-classifications: passed, findings 0, new 0, on main 0, waived 0, 23 columns checked
with the fix, coverage/ai.review_corpus: no metadata; on main, owner team-platform
with the fix, coverage/marketing.audience: no metadata; on main, owner team-platform
with the fix, change learning.courses, field 3: renamed from category string to subject string; named by 2 pipelines, reaches 12 columns
with the fix, job: passed
Iceberg については、何も壊れなかった。名前の変更でも列のフィールド ID は保たれたので、ブランチ上の Iceberg の読み手は、200 件のコースについて subject を引き続き見つけられる。SQL については、この列の名前を指定するパイプライン course_performance, marketing_audience が、ブランチ上では何も書き込む前にそれぞれ停止する。4 章で、読み取れない系譜をエラーとしたためである。値を通じた場合、名前変更の影響は 2 列、つまりカテゴリの 2 つのコピーに及ぶ。すべてのエッジを通じた場合は 12 列に及び、これは analytics.course_performance, marketing.audience のすべての列である。カテゴリがコースレポートをグループ化し、各学習者のお気に入りの順位付けにも使われるからである。報告の送付先は no owner, team-analytics である。つまり分析チームであり、まだ所有者のいない marketing.audience については送付先がない。
ビルドが壊れると、何が壊れたかが見えなくなる。ブランチのカタログにあるテーブルは 10 個で、main の 12 個より少ない。壊れたパイプラインが何も書き込まなかったためである。カバレッジの報告は coverage/ai.review_corpus だけである。存在しないテーブルは説明のないものとして見つけられないので、marketing.audience の指摘は消えている。各側がそれぞれ pipelines/ を実行するので、修正は名前変更と一緒に届く。両方のパイプラインが subject を読むようになれば、ジョブは passed と報告する。本番では、マージによって、レビューで確認した内容を保護することもできる。REST カタログのコミットは AssertCurrentSchemaId を持てる。これは、テーブルの現在のスキーマ ID が要件で指定された ID と一致することを求めるので(REST catalog spec, 1.12.0)、あるスキーマに対してレビューされたマイグレーションは、別のスキーマに適用されることなく失敗する。
実践ルール: スキーマの差分は、名前やスキーマ ID ではなくフィールド ID で取る。名前の変更、型の変更、削除は、すべて 3 つの観点で報告する。Iceberg の読み手が影響を受けるかどうか、どのパイプラインの SQL がその列の名前を指定しているか、そして INDIRECT エッジを含め系譜を通じて何に及ぶか、である。報告は、影響が及ぶすべてのテーブルの所有者に送る。パイプラインを壊す名前変更は、そのパイプラインの修正と同じプルリクエストでマージし、修正より先にマージしてはならない。
分類を下げる前に所有者に確認する
破壊的変更の検査ツールは、スキーマの読み手を守る。dbt のモデルコントラクトは、列の削除やデータ型の変更を、下流の利用者に影響しうる破壊的変更として検出する(dbt model contracts)。datacontract-cli の breaking コマンドは、2 つの ODCS コントラクトを比較し、利用者が依拠している保証を壊す変更を失敗させる(datacontract-cli 1.2.7)。ただし、どちらも保護を保証として扱ってはいない。datacontract-cli 1.2.7 には、プロパティの分類やチームメンバーのロールを対象とするルールがない。そのため、どちらを変更しても、未検証と記録するルールが適用される(rules.py)。検出器はこうした変更を INFO で報告する(detector.py)。このレベルでは失敗しない。コマンドが終了コード 1 で終わるのは ERROR の項目があるときだけである(コマンドの実装、破壊的変更のモデル)。examples/requirements.txt はこのツールを固定していないため、どの例もこれを実行しない。2026 年 10 月 22 日に、本章が crm.learners について生成するコントラクトに対して datacontract-cli 1.2.7 を実行した。名前を変更した email は、終了コード 1 で失敗した。プロパティは id を保っていたが、ツールはプロパティを名前で照合するため、この変更を削除と解釈した(normalize.py)。一方、email を personal から public へ再分類した変更と、所有者の変更は、終了コード 0 で通った。ODCS 自体も、分類は「何でもよい」としている(ODCS v3.2.0 schema)。
しかし、すべてのポリシーは分類を読む。したがって、分類を下げることは、メタデータファイルに含まれうる変更のなかで最も影響の大きいものの一つである。そこで、独自の最初のルールを加える。列の分類を下げる変更、テーブルの所有者を変える変更、テーブルを別のドメインへ移す変更には、main ブランチでそのテーブルを所有するチームの承認が必要である。移動は所有権の変更とみなす。ドメイン固有のルールが、そのドメインのテーブルに適用されるためである(後の節)。所有者は main ブランチから取る。そうしないと、プルリクエストがテーブルを新しい所有者に渡し、その新しい所有者が分類の引き下げを承認できてしまうからである。第 2 章は、モデルの草案について同じルールを定めた。分類を下げられるのはレビュー担当者だけであり、その理由は列の説明に記す。
最後に来るのは、データサイエンスチームのプルリクエストである。このプルリクエストは、データサイエンティストが学習者を都市別に集計できるように、crm.learners.city を personal から internal に下げる。アクセスポリシーは、データサイエンティストに対して個人情報の列を仮名化する。分類の引き下げにより、city はこのルールの対象から外れる。実行では、変更の前後についてポリシーに問い合わせ、スキーマとポリシーを調べる検査と、所有者ルールを実行する。
1"""A pull request from the data-science team lowers crm.learners.city from personal to internal. The prose's point rests2on analyst-1's mask on each side, and on the owner rule failing alone."""3from lib import ci, policy45main = ci.checkout()6branch = ci.checkout(main)7ci.edit(branch, "governance/metadata.toml", '6 = { name = "city", classification = "personal"',8 '6 = { name = "city", classification = "internal"')9before, after = ci.build(main), ci.build(branch)1011reading_city = policy.request("analyst-1", "crm.learners", ["learner_id", "city"])12for side, name in ((before, "main"), (after, "the branch")):13 rego = policy.interpreter(side.governance / "policies", data=ci.policy_data(side))14 # a column with no mask in the decision is shown as it is stored15 print(f"analyst-1 reading city, on {name}:", policy.decide(reading_city, rego)["column_masks"].get("city", "unmasked"))1617checks = ["policy-tests", "enforcement-tests", "removals", "owner-review"]18report = ci.run(before, after, checks=checks)19print("schema changes:", len(report.changes))20for line in ci.lines(report):21 print(line)2223# The approvals come from the pull request's reviews: one entry per approving review, named by the reviewer's team.24# The owner rule passes when it raises no unapproved finding.25owner_review = lambda approvals: "passed" if ci.run(before, after, approvals, checks=["owner-review"]).passed else "failed"26print("owner-review, once team-crm approves:", owner_review(["team-crm"]))27print("owner-review, once team-analytics approves:", owner_review(["team-analytics"]))28ci.edit(after.root, "governance/ci.toml", "teams = {}", "teams = { team-crm = 2 }") # team-crm asks for two29# one approval from team-crm and one from another team: team-crm still needs a second of its own30print("owner-review, two required, one from team-crm:", owner_review(["team-crm", "team-platform"]))31print("owner-review, two required, two from team-crm:", owner_review(["team-crm", "team-crm"]))
python classification-downgrade.pyanalyst-1 reading city, on main: pseudonymize
analyst-1 reading city, on the branch: unmasked
schema changes: 0
policy-tests: passed, findings 0, new 0, on main 0, waived 0, 24 tests and rows checked
enforcement-tests: passed, findings 0, new 0, on main 0, waived 0, 44 cases checked
removals: passed, findings 0, new 0, on main 0, waived 0, 87 columns checked
owner-review: failed, findings 1, new 1, on main 0, waived 0, 77 columns checked
owner-review/crm.learners.city: lowered from personal to internal; needs team-crm's approval
job: failed
owner-review, once team-crm approves: passed
owner-review, once team-analytics approves: failed
owner-review, two required, one from team-crm: failed
owner-review, two required, two from team-crm: passed
メタデータファイルの 1 語が、ロール全体に対して列のマスキングを解除する。所有者ルール以外の検査は、これに気づかない。analyst-1 は、city を main では pseudonymize として、ブランチでは unmasked として読む。ジョブはスキーマの変更を 0 と報告するため、破壊的変更の検査ツールには比較するものがない。ポリシーのテストは passed, findings 0, new 0, on main 0, waived 0, 24 tests and rows checked のとおり成功し、適用のテストも成功する。どれも city を読まないからである。削除の検査も、削除された列がないため成功する。失敗するのは所有者ルールだけであり、lowered from personal to internal; needs team-crm's approval で失敗する。
所有者ルールを解消するのは、所有者の承認である。承認は、承認したレビューごとに 1 項目として lib.ci.run に届き、レビュー担当者のチーム名で示される。team-crm の承認があれば、所有者ルールは passed と報告する。テーブルを所有しない team-analytics の承認では、所有者ルールは failed と報告する。
実践ルール: 分類の引き下げ、所有者の変更、別のドメインへの移動は、main ブランチでそのテーブルの所有者の承認が必要な変更として扱い、承認されるまでジョブを失敗させる。これらについて、破壊的変更の検査ツールに頼ってはならない。同じプルリクエストで、その理由を列の説明に記すよう求める。分類の引き上げには、このような承認は不要である。引き上げは、より多くを隠すだけだからである。
列を削除する前に非推奨にする
所有者ルールは、破壊的変更の検査ツールが見落とす変更を防ぐ。列の削除はそれらがすべて検出する変更であるが、その時点ですでに削除はレビューの段階にあり、影響を受ける読み手を助けるには遅すぎる。ODCS 3.2.0 は、読み手に先に警告するための手段を加えている。契約のどの要素も(スキーマオブジェクトでもプロパティでもよく、入れ子になったものも含む)、任意のブール値 deprecated を設定することで、その要素がもはや利用を推奨されないことを示せる。標準はさらに、description が代替手段を指し示し、移行の指針を与えることを求めている(ODCS v3.2.0 schema)。2つ目のルールは、この非推奨の警告を必須の手順にする。列がテーブルから外れてよいのは、main ブランチがその列を非推奨と記録した後に限る。これには2つのプルリクエストが必要であり、1つは列を非推奨にし、もう1つは列を削除する。両者の間に、その列の読み手は列から離れるための時間を得られる。
プラットフォームのメタデータファイルにはこのようなフィールドがなかったため、この章で追加する。列のエントリに deprecated = true と書く形である。lib.metadata.load はこれを Column.deprecated として読み込み、記載がなければ false とし、lib.ci.contract はそれを ODCS の deprecated として列の契約に書き出す。
プラットフォームで最も適した候補は billing.payments.card_number である。この列自身の description に「Should not be stored at all」とあり、第3章では、この列にカード番号の全桁が保存されていることが分かった。team-billing はこの列を2回削除する。いずれも、マイグレーションで列を落とし、そのメタデータのエントリを削除する方法である。1回目は即座に行い、2回目は列を非推奨にするプルリクエストがマージされた後に行う。
1"""team-billing removes the legacy card_number column from billing.payments: once straight away, and once after a pull2request that deprecates it has merged. The prose's point rests on the two removal lines."""3import yaml45from lib import ci67entry = ('8 = { name = "card_number", classification = "sensitive", '8 'description = "The full card number, from a legacy export. Should not be stored at all." }\n')9# the note goes after the description's sentence ending "at all.", and deprecated = true goes inside the entry's braces10deprecated_entry = entry.replace("all.", "all. Deprecated: reconcile payments by payment_id.").replace(" }", ", deprecated = true }")111213def remove_card_number(base, line):14 """A pull request on top of `base` that drops the column and deletes its metadata entry."""15 branch = ci.checkout(base)16 (branch / "migrations" / "0001-drop-card-number.sql").write_text("alter table billing.payments drop column card_number;\n")17 ci.edit(branch, "governance/metadata.toml", line, "")18 return branch192021main = ci.checkout()22deprecated = ci.checkout(main) # the first pull request: mark the column deprecated, and say what replaces it23ci.edit(deprecated, "governance/metadata.toml", entry, deprecated_entry)2425for base, line, name in ((main, entry, "straight away"), (deprecated, deprecated_entry, "after the deprecation merged")):26 report = ci.run(ci.build(base), ci.build(remove_card_number(base, line)), checks=["removals"])27 print(f"removal, {name}:", "passed" if report.checks[0].passed else "failed")28 for finding in report.checks[0].findings:29 print(f" {finding.id}:", finding.message)3031# property 7 is the eighth column, field 8: card_number, the column the deprecation marks32card_number = ci.contract(ci.build(deprecated), "billing.payments")["schema"][0]["properties"][7]33print("the deprecated column in its ODCS contract:")34print(yaml.safe_dump(card_number, sort_keys=False, width=200), end="")
python deprecate-then-remove.pyremoval, straight away: failed
removals/billing.payments.card_number: removed without being deprecated on the main branch first
removal, after the deprecation merged: passed
the deprecated column in its ODCS contract:
id: field-8
name: card_number
logicalType: string
physicalType: string
required: false
description: 'The full card number, from a legacy export. Should not be stored at all. Deprecated: reconcile payments by payment_id.'
classification: sensitive
deprecated: true
即座に行った削除は失敗し、removed without being deprecated on the main branch first。非推奨がマージされた後では、同じ削除が passed と報告される。その間に、契約は警告を、リポジトリだけでなく契約を読むすべての人に伝えていた。それが deprecated: true であり、description にはこの列なしで支払いを突合する方法が書かれている。このルールが検査するのは2つの変更の順序であり、その間の期間ではない。読み手にどれだけの猶予を与えるかは、所有するチームと列の読み手が決めることであり、その読み手が誰であるかは影響レポートが示す。
実践ルール: 列の削除は2つのプルリクエストに分ける。まず列を非推奨にし、代替手段を description に記してマージする。次に、テーブルから列を落とし、メタデータからそのエントリを削除する。main ブランチが非推奨にしていない列の削除は、すべて失敗させる。非推奨の期間は列の読み手と合意しておく。ジョブが確認するのは、非推奨が先に行われたことだけだからである。
この部分はまだ翻訳されていないため、英語で表示している。
Route each domain's reviews by path
The owner rule asks a table's team to approve its downgrades, and the repository can route that request. GitHub requests code owners' review automatically when a pull request modifies code they own, and a branch protection rule can require that review (GitHub's documentation, About code owners). The platform keeps all its metadata in one file, governance/metadata.toml, which suits 5 teams in one repository. A file has one set of owners, though, so the request can reach the right team only if each team's metadata lives under a path of its own.
ODCS draws the same lines. A contract names one domain, the logical data domain it belongs to (ODCS v3.2.0 fundamentals). ODCS has no owner field: ownership is a free-form role on a member of the contract's team (ODCS v3.2.0 team). lib.ci.contract writes each described table as an ODCS contract. It records the domain, the owning team as a member with the role owner, and each column as a property whose id holds its Iceberg field ID. ODCS defines a property's id as "A unique identifier for the element used to create stable, refactor-safe references". lib.ci.generate writes each contract into a folder for its domain, and a CODEOWNERS file in .github/, the first place GitHub looks for one. Both are generated from the metadata, never typed. Ask whom GitHub would request for the data-science team's downgrade of city:
1"""Ownership as ODCS contracts, a folder per domain, and who GitHub asks to review the downgrade of crm.learners.city2when the metadata is one shared file, and when each domain has a folder of contracts generated from it. The prose's3point rests on the first review line and on the contracts check failing before the files are generated again."""4import yaml56from lib import ci78main = ci.checkout() # the main branch holds the contracts and CODEOWNERS generated from its metadata9branch = ci.checkout(main)10ci.edit(branch, "governance/metadata.toml", '6 = { name = "city", classification = "personal"',11 '6 = { name = "city", classification = "internal"')1213shared = ["/governance/ @example-org/team-platform"] # one file for every domain, owned by the platform team14for path, owners in ci.reviewers(shared, ["governance/metadata.toml"]).items():15 print(f"one shared file, review of {path}:", " ".join(owners))1617crm = yaml.safe_load((main / "governance/contracts/crm/learners.odcs.yaml").read_text(encoding="utf-8"))18print(yaml.safe_dump({"domain": crm["domain"], "team": crm["team"]}, sort_keys=False), end="")19lines = (main / ".github/CODEOWNERS").read_text(encoding="utf-8").splitlines()20for line in lines[1:]: # the first line says the file is generated21 print("CODEOWNERS", line)22before, after = ci.build(main), ci.build(branch) # the pull request changes the metadata only23print("teams that own tables:", len({table.owner for table in before.described.values()}))24# drops the job's verdict, the last line, which this example doesn't print25for line in ci.lines(ci.run(before, after, checks=["contracts"]))[:-1]:26 print("before generating again,", line)27print("files generated again:", len(ci.generate(after)))28print("after generating again, contracts:", "passed" if ci.run(before, after, checks=["contracts"]).passed else "failed")29# the last matching CODEOWNERS line wins, as GitHub applies it30for path, owners in ci.reviewers(lines, ci.changed(main, branch)).items():31 print(f"a folder per domain, review of {path}:", " ".join(owners))
python domain-contracts.pyone shared file, review of governance/metadata.toml: @example-org/team-platform
domain: crm
team:
name: team-crm
members:
- username: team-crm
role: owner
CODEOWNERS /.github/CODEOWNERS @example-org/team-platform
CODEOWNERS /governance/ @example-org/team-platform
CODEOWNERS /migrations/ @example-org/team-platform
CODEOWNERS /pipelines/ @example-org/team-platform
CODEOWNERS /pipelines/course_performance.sql @example-org/team-analytics
CODEOWNERS /pipelines/learner_activity.sql @example-org/team-analytics
CODEOWNERS /governance/contracts/analytics/ @example-org/team-analytics
CODEOWNERS /governance/contracts/billing/ @example-org/team-billing
CODEOWNERS /governance/contracts/crm/ @example-org/team-crm
CODEOWNERS /governance/ci/domains/crm.rego @example-org/team-crm
CODEOWNERS /governance/contracts/learning/ @example-org/team-learning
CODEOWNERS /governance/contracts/support/ @example-org/team-support
teams that own tables: 5
before generating again, contracts: failed, findings 1, new 1, on main 0, waived 0, 11 files checked
before generating again, contracts/governance/contracts/crm/learners.odcs.yaml: differs from what the metadata generates: generate it again
files generated again: 11
after generating again, contracts: passed
a folder per domain, review of governance/contracts/crm/learners.odcs.yaml: @example-org/team-crm
a folder per domain, review of governance/metadata.toml: @example-org/team-platform
With one shared file, the downgrade changes governance/metadata.toml, and GitHub asks @example-org/team-platform to review it. That is the team that owns the file, not team-crm, whose column it is. The generated CODEOWNERS gives the platform team the file itself, because About code owners says a repository is fully protected against unauthorized changes only when the CODEOWNERS file itself has an owner (GitHub's documentation). The platform team also gets the governance files, the migrations and the pipelines. Each pipeline then goes to the team that owns its table, and each folder of contracts goes to its domain's team. The pull request changed only the metadata, so the contracts check, which generates every file again and compares, fails: differs from what the metadata generates: generate it again. Generated again, the pull request also changes the crm contract, and its review goes to @example-org/team-crm, because GitHub gives the last matching pattern precedence. A hook that generates the files saves the author a failed run. The check makes the routing certain.
When code-owner review is required, an approval from any one of a file's owners meets it (About code owners). Branch protection asks for one number of approvals for the whole branch, met by reviewers with write permissions (GitHub, protected branches), so any such reviewer counts toward it, and it can't ask for two of team-crm's members. The job can, from the approvals it's given. The owner rule counts them per team, against a number per team in ci.toml. With team-crm asking for two, the downgrade of city with one team-crm approval reports failed, and with two it reports passed. Iceberg 1.12.0's REST catalog spec offers another place for classifications, labels per table and field ID (REST catalog spec). Coverage and the contract rules could read a catalog server's labels, but changes to them would need the server's own review, since the spec doesn't require that labels be persisted or versioned.
Working rule: Keep each domain's metadata under a path of its own, as one ODCS contract per table with one domain and one owning team, generated from the metadata and checked by the job, with a CODEOWNERS line for that team. Give the platform team the CODEOWNERS file, the job's settings, its global rules, the waivers and the migrations. Require code-owner review, and count approvals per team in the job when one isn't enough.
グローバルルールの上にドメインルールを重ねる
各ドメインの契約を所有するチームも、一つのプラットフォームを共有しており、すべてのドメインで守られなければならないルールがある。Dehghani はデータメッシュの説明の中でこれを連合型の計算によるガバナンス(federated computational governance)と呼び、「健全で相互運用可能なエコシステムを保証するための、グローバルルールの集合、すなわちすべてのデータプロダクトとそのインターフェースに適用されるルール」と述べている。これらのグローバルルールは、各ドメインが自ら下す決定と並んで存在し、プラットフォームがその両方を実行する(Dehghani, 2020)。これは測定ではなく枠組みであるが、コードに対応づけることができる。プラットフォームチームはグローバルルールのパッケージを一つ保持し、その内容は各ドメインが合意する。Dehghani の説明では、ドメインのプロダクトオーナーとプラットフォームのプロダクトオーナーが共同でこれを決める。各ドメインにはそのチームが所有する独自のパッケージがあり、一つのジョブがそれらをすべて実行する。
OPA プロジェクトでファイルに対するルールを扱うツールは Conftest であり、構造化された設定データを Rego でテストする(Conftest)。lib.ci は、第5章がアクセスポリシーを実行するのと同様に、同種のルールを regopy でプロセス内で実行する。governance/ci/global.rego にはグローバルルールが置かれている。ロールの大文字小文字にかかわらず、オーナーが一つであること。ドメインは一つであること。値が存在しない、空、または空白のみの場合は失敗とする。Rego では空文字列も定義された値であり、not だけでは通過してしまうためである。分類は四つのうちのいずれかであること。ODCS は任意の文字列を受け入れるためである。すべてのカラムに説明があること。governance/ci/domains/crm.rego には team-crm のルールが置かれている。crm のものは何も公開(public)にしてはならない。その中のすべてが学習者または講師を記述しているためである。contract-rules のチェックは、すべての契約に対してグローバルパッケージを実行し、ブランチ上の各ドメインの契約に対しては、そのドメインのパッケージを実行する。ルールは違反をデータとして返し、そこにはルール名、対象、メッセージが含まれる。違反の対象とルール名が、検出結果の ID を構成する。これらのファイルはアクセスポリシーのフォルダである governance/policies/ の外に置かれるため、変更しても、第8章が判定のたびに記録するポリシーのリビジョンは変わらない。
CRM チームの変更が、今度はメタデータ付きで戻ってくる。work_email は、勤務先のアドレスは業務情報であるという理由で public に分類されており、その説明は空である。二度目の試みでは説明を追加し、crm.learners を独自のルールを持たないアナリティクスドメインへ移す。
1"""The platform's global rules and the crm domain's own rule, run on the CRM team's two tries at work_email: classified2public with no description, then described with crm.learners moved to the analytics domain, which has no rules of its own.3The prose's point rests on the two contract-rules findings of the first try and on the owner-review finding after the move."""4from lib import ci56main = ci.checkout()7branch = ci.checkout(main)8(branch / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")9ci.edit(branch, "governance/metadata.toml", '15 = { name = "notes"',10 '16 = { name = "work_email", classification = "public", description = "" }\n15 = { name = "notes"')1112for path in sorted((branch / "governance" / "ci").rglob("*.rego")):13 print("rules:", path.relative_to(branch).as_posix())14before = ci.build(main)15report = ci.run(before, branch, checks=["coverage", "contract-rules"])16for line in ci.lines(report):17 print(line)1819# The second try: a description, and the table moved to a domain whose rules allow public columns.20ci.edit(branch, "governance/metadata.toml", 'description = "" }', 'description = "The learner\'s work address." }')21# the table's domain changes from crm to analytics, which has no rules of its own22ci.edit(branch, "governance/metadata.toml", 'owner = "team-crm"\ndomain = "crm"\ndescription = "Every learner',23 'owner = "team-crm"\ndomain = "analytics"\ndescription = "Every learner')24report = ci.run(before, branch, checks=["coverage", "contract-rules", "owner-review"])25for line in ci.lines(report):26 print("moved to analytics,", line)
python global-and-domain-rules.pyrules: governance/ci/domains/crm.rego
rules: governance/ci/global.rego
coverage: failed, findings 3, new 1, on main 2, waived 0, 12 tables checked
contract-rules: failed, findings 2, new 2, on main 0, waived 0, 10 contracts checked
coverage/ai.review_corpus: no metadata; on main, owner team-platform
coverage/crm.learners.work_email: classified public; its name suggests personal; needs team-crm's approval
coverage/marketing.audience: no metadata; on main, owner team-platform
contract-rules/crm.learners.work_email/described: no description (global rule described)
contract-rules/crm.learners.work_email/no-public: crm classifies no column public (domains.crm rule no-public)
change crm.learners, field 16: added as work_email string; named by 0 pipelines, reaches 0 columns
job: failed
moved to analytics, coverage: failed, findings 3, new 1, on main 2, waived 0, 12 tables checked
moved to analytics, contract-rules: passed, findings 0, new 0, on main 0, waived 0, 10 contracts checked
moved to analytics, owner-review: failed, findings 1, new 1, on main 0, waived 0, 77 columns checked
moved to analytics, coverage/ai.review_corpus: no metadata; on main, owner team-platform
moved to analytics, coverage/crm.learners.work_email: classified public; its name suggests personal; needs team-crm's approval
moved to analytics, coverage/marketing.audience: no metadata; on main, owner team-platform
moved to analytics, owner-review/crm.learners/domain: domain changed from crm to analytics; needs team-crm's approval
moved to analytics, change crm.learners, field 16: added as work_email string; named by 0 pipelines, reaches 0 columns
moved to analytics, job: failed
カバレッジは今度は分類を指摘する。classified public; its name suggests personal; needs team-crm's approval名前は証拠であり、プルリクエストには読み取るべき値がないため、名前が示唆する分類より低い分類は、main 上のオーナーだけが答えられる指摘となる。
契約ルールはさらに多くを求める。グローバルパッケージは no description (global rule described) を指摘し、crm パッケージは crm classifies no column public (domains.crm rule no-public) を指摘する。team-crm は二つ目のルールを他のどのチームにも諮らずに決め、プラットフォームがそれを、team-crm からのプルリクエストを含むすべてのプルリクエストで代わりに実行する。
二度目の試みでは、アナリティクスドメインのルールが適用され、契約ルールは通過する。passed, findings 0, new 0, on main 0, waived 0, 10 contracts checked。移動そのものは domain changed from crm to analytics; needs team-crm's approval で失敗し、分類も同様に失敗する。
実践ルール: すべてのドメインが従うべきルールは、プラットフォームチームが保持する一つのグローバルパッケージとして書く。各ドメインには、そのチームが所有し、そのドメインの契約にのみ実行される独自のパッケージを追加させる。違反は、単なる合否ではなく、安定した対象を持つデータとして返す。ドメインのルールはグローバルルールに追加するものであり、置き換えるものではない。また、テーブルの別ドメインへの移動は所有権の変更として扱う。そうすれば、一語を変えることで自分のドメインのルールを逃れるチームは現れない。
チェックごとに免除済みの指摘を数える
ここまでのチェックは、いずれも何らかの理由でプルリクエストを失敗させる。ゲートは、人々がそれを信頼しなくなったときにも機能しなくなる。GoogleのTricorderの著者らは、実効的な偽陽性を、ユーザーが対処しないことを選んだあらゆる報告と定義し、コードレビュー時のその比率を10%未満に保っている。実際に対処されるものはそれより狭く、有用でない率(not-useful rate)がそれにあたる。これは、あるアナライザーについて、Not useful、Please fix、Apply fix の各クリックの合計に占める Not useful クリックの割合である。この率が10%以上になるとアナライザーは保護観察(probation)に置かれ、25%を超えると直ちに停止されることがある(Sadowski et al., 2015)。これは一企業のコード解析であり、しきい値も同社が独自に定めたものである。データガバナンスについて公表された同等の基準は、我々の知る限り存在しない。この尺度は類推として適用できる。チェックごとに、誰も対処しない指摘を数える。対象は、免除されたものと main に残されたものである。
このプラットフォームでは、新しい指摘に対処しないという判断が免除(waiver)である。governance/waivers.toml の免除は、1件の指摘をその ID で指定し、あわせて、その責任を負うチーム、理由、そして免除が有効な最終日を記す。lib.ci は、ジョブを実行する日から数えて最長90日先までの免除を受け付ける。この上限は governance/ci.toml に置かれた経験則であり、すべての免除は再び判断の場に戻ってくる。同じファイルには、日付にかかわらずどの免除でも黙らせることができないチェックも列挙されている。カバレッジ(所有者のないテーブルや分類のない列はプルリクエストの中で修正されるため)と、強制テストである。すでに main にある指摘には免除は不要である。期限切れの免除は何も黙らせず、レポートにそれが一覧表示される。免除ファイルはプラットフォームチームが管理するため、個々の免除もレビューを受ける変更となる。
CRM の変更には2件の免除が必要である。1件目は未分類の列を対象とする。2件目は、その列を personal に分類した後に、まだ書かれていない説明を対象とする。チームは2件目をまず夏まで、次に10月31日までとして申請する。
1"""Waivers on the CRM team's pull request: one for the unclassified work_email column, which coverage never allows;2then, with the column classified but not yet described, one that asks for too long, and one that fits, on the book's3today and a month later. The prose's point rests on the two refusals and on the expired waiver the report lists."""4from datetime import date56from lib import ci7from lib.platform import TODAY8910def waive(branch, finding, expires, reason):11 with open(branch / "governance" / "waivers.toml", "a", encoding="utf-8") as waivers:12 # the date is written unquoted, so TOML reads it as a date, which the job compares with the day it runs13 waivers.write(f'\n[[waivers]]\nfinding = "{finding}"\nowner = "team-crm"\nreason = "{reason}"\nexpires = {expires}\n')141516main = ci.checkout()17before = ci.build(main)18unclassified = ci.checkout(main)19(unclassified / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")20waive(unclassified, "coverage/crm.learners.work_email", "2026-10-31", "Classified once the sign-up form is live.")21for line in ci.lines(ci.run(before, unclassified, checks=["coverage"])):22 print("unclassified,", line)2324undescribed = ci.checkout(main) # the second try: classified, with its description still to come25(undescribed / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")26ci.edit(undescribed, "governance/metadata.toml", '15 = { name = "notes"',27 '16 = { name = "work_email", classification = "personal", description = "" }\n15 = { name = "notes"')28waive(undescribed, "contract-rules/crm.learners.work_email/described", "2027-06-30", "Described once the form's copy is final.")29after = ci.build(undescribed)30for line in ci.lines(ci.run(before, after, checks=["coverage", "contract-rules"])):31 print("undescribed, asked until 2027-06-30,", line)3233# the same waiver, shortened to the end of October, within the longest a waiver may run34ci.edit(undescribed, "governance/waivers.toml", "2027-06-30", "2026-10-31")35for day in (TODAY, date(2026, 11, 1)): # the book's today, then a month later, after the waiver has expired36 report = ci.run(before, after, today=day, checks=["coverage", "contract-rules"])37 print(f"undescribed, asked until 2026-10-31, on {day}, contract-rules:", "passed" if report.checks[1].passed else "failed")38 print(f"undescribed, asked until 2026-10-31, on {day}, findings waived:", sum(len(c.waived) for c in report.checks))39 print(f"undescribed, asked until 2026-10-31, on {day}, waivers that silence nothing:",40 "; ".join(why for _, why in report.unused) or "none")
python waived-findings.pyunclassified, coverage: failed, findings 3, new 1, on main 2, waived 0, 12 tables checked
unclassified, coverage/ai.review_corpus: no metadata; on main, owner team-platform
unclassified, coverage/crm.learners.work_email: not classified; its name suggests personal
unclassified, coverage/marketing.audience: no metadata; on main, owner team-platform
unclassified, change crm.learners, field 16: added as work_email string; named by 0 pipelines, reaches 0 columns
unclassified, waiver coverage/crm.learners.work_email: silences nothing, coverage findings are never waived
unclassified, job: failed
undescribed, asked until 2027-06-30, coverage: passed, findings 2, new 0, on main 2, waived 0, 12 tables checked
undescribed, asked until 2027-06-30, contract-rules: failed, findings 1, new 1, on main 0, waived 0, 10 contracts checked
undescribed, asked until 2027-06-30, coverage/ai.review_corpus: no metadata; on main, owner team-platform
undescribed, asked until 2027-06-30, coverage/marketing.audience: no metadata; on main, owner team-platform
undescribed, asked until 2027-06-30, contract-rules/crm.learners.work_email/described: no description (global rule described)
undescribed, asked until 2027-06-30, change crm.learners, field 16: added as work_email string; named by 0 pipelines, reaches 0 columns
undescribed, asked until 2027-06-30, waiver contract-rules/crm.learners.work_email/described: silences nothing, runs to 2027-06-30, past the longest allowed, 2026-12-30
undescribed, asked until 2027-06-30, job: failed
undescribed, asked until 2026-10-31, on 2026-10-01, contract-rules: passed
undescribed, asked until 2026-10-31, on 2026-10-01, findings waived: 1
undescribed, asked until 2026-10-31, on 2026-10-01, waivers that silence nothing: none
undescribed, asked until 2026-10-31, on 2026-11-01, contract-rules: failed
undescribed, asked until 2026-10-31, on 2026-11-01, findings waived: 0
undescribed, asked until 2026-10-31, on 2026-11-01, waivers that silence nothing: expired on 2026-10-31
未分類の列に対する免除は、1か月だけを求めているにもかかわらず却下される。silences nothing, coverage findings are never waived である。どの免除でも、このプルリクエストを通過させることはできない。説明に対する免除は、夏までの期間では却下される。silences nothing, runs to 2027-06-30, past the longest allowed, 2026-12-30 である。10月31日までに短縮すると、その指摘は黙らされる。10月1日には、契約ルールは passed と報告する。11月1日には failed と報告する。何も黙らせない免除の一覧は、10月1日には none であり、11月1日には expired on 2026-10-31 である。日付は過ぎたが、問題は解消していない。
実践ルール: 免除は、プルリクエストが持ち込む指摘をちょうど1件だけ指定し、担当チーム、理由、そして数か月以内の終了日を添えること。分類や所有者の欠落のように、どの免除でも黙らせてはならないチェックを列挙しておくこと。チェックごとに、誰も対処しなかった指摘(免除されたものと main に残されたもの)の件数を報告し、指摘の大半がそれにあたるチェックはレビューすること。チェックが誤っているか、プラットフォームが誤っているかのどちらかであり、件数だけではそのどちらかは分からない。
本番環境で何が問題になるか
我々の判断では、ガバナンスジョブは、壊れるよりも無効化されることのほうが多い。チームは遅いチェックやノイズの多いチェックを、governance/ci.toml の1行ずつ取り除いていく。その間もゲートは通過し続けるが、守る範囲は狭くなっていく。2つの段階的なチェックがその過程を示す。所要時間の代わりに件数を用いる。3つ目は、壊れるジョブを示す。
この部分はまだ翻訳されていないため、英語で表示している。
A check that reads every row
The support team adds two columns to support.tickets: callback_number, classified internal, and reply_email, classified public. A team that wants values judged, not only names, then adds chapter 3's classification of the table to the job, by sample and by every row:
1"""The support team's pull request adds two columns to support.tickets, which coverage judges by their names and chapter23's value checks judge by reading a sample, or every row. The prose's point rests on the callback number's empty column3and on the values each check reads; counts of values stand in for time, which depends on the machine."""4import pyarrow as pa56from lib import ci, pii78main = ci.checkout()9branch = ci.checkout(main)10(branch / "migrations" / "0001-callback-and-reply.sql").write_text(11 "alter table support.tickets add column callback_number varchar;\n"12 "alter table support.tickets add column reply_email varchar;\n")13ci.edit(branch, "governance/metadata.toml", '8 = { name = "status"',14 '9 = { name = "callback_number", classification = "internal", description = "A number to call the learner back on." }\n'15 '10 = { name = "reply_email", classification = "public", description = "Where the reply goes." }\n8 = { name = "status"')16before, after = ci.build(main), ci.build(branch)1718report = ci.run(before, after, checks=["coverage", "classify-sampled", "classify-every-row"])19for name in ("body", "callback_number", "reply_email"):20 values = after.catalog.load_table("support.tickets").scan(selected_fields=(name,)).to_arrow()[name]21 print(f"support.tickets.{name}, values on the branch:", f"{len(values) - values.null_count:,}")22 for check in report.checks:23 found = [f.message for f in check.findings if f.id == f"{check.name}/support.tickets.{name}"]24 print(f"support.tickets.{name}, {check.name}:", found[0] if found else "no finding")25for check in report.checks[1:]:26 print(f"{check.name}, values read:", f"{check.checked:,}")2728text_columns, sampled, every_row = 0, 0, 029for name in sorted(before.described):30 data = before.catalog.load_table(name).scan().to_arrow()31 # the non-null values of each text column, the ones a value check classifies32 filled = [len(column) - column.null_count for column in data.columns if pa.types.is_string(column.type)]33 text_columns += len(filled)34 # the sampled check reads at most pii.ROWS values of each column35 sampled += sum(min(pii.ROWS, count) for count in filled)36 every_row += sum(filled)37print("text columns in the described tables:", text_columns)38print("values the sampled check would read in them:", f"{sampled:,}")39print("values the every-row check would read in them:", f"{every_row:,}")
python slow-check-every-row.pysupport.tickets.body, values on the branch: 2,000
support.tickets.body, coverage: no finding
support.tickets.body, classify-sampled: values support sensitive, reviewed as personal
support.tickets.body, classify-every-row: values support sensitive, reviewed as personal
support.tickets.callback_number, values on the branch: 0
support.tickets.callback_number, coverage: no finding
support.tickets.callback_number, classify-sampled: no finding
support.tickets.callback_number, classify-every-row: no finding
support.tickets.reply_email, values on the branch: 0
support.tickets.reply_email, coverage: classified public; its name suggests personal; needs team-support's approval
support.tickets.reply_email, classify-sampled: its name suggests personal, reviewed as public
support.tickets.reply_email, classify-every-row: its name suggests personal, reviewed as public
classify-sampled, values read: 1,000
classify-every-row, values read: 10,000
text columns in the described tables: 32
values the sampled check would read in them: 5,800
values the every-row check would read in them: 429,453
Coverage fails reply_email by its name, classified public; its name suggests personal; needs team-support's approval, and passes callback_number, no finding, because no name rule matches it. The branch holds 0 values in the new column, so reading values doesn't help yet either. The migration adds the column empty, and every row gives no finding. Chapter 3's scheduled sample catches the phone numbers once the column fills.
The sampled check reads 1,000 values and the every-row check reads 10,000. Both find support.tickets.body sensitive under a personal classification, which chapter 3 already sent to team-support. Across every text column in the described tables, a sample would read 5,800 values, and every row would read 429,453. The second number grows with the data, on every pull request, whatever the pull request changed. A job that keeps people waiting, we judge, gets skipped, and then removed.
Working rule: Size pull-request checks by the change, not by the data: metadata, schemas, policies and the names of the columns a pull request adds. Run checks that read values on a schedule, with a fixed sample, as chapter 3 does, and send their findings to the owning team. Document where the job's checks stop, such as at a column added empty.
すべての ID を検出するチェック
慎重なチームが、ID のような名前を持つ列をすべて個人データとして扱うチェックを追加する。しかし、結合に使う ID については、プラットフォームが別の判断を下している。第2章では learner_id を internal に分類し、それを解決するテーブルを保護している。このチェックの検出結果は新規のものであるため、各担当チームはそれらを免除する。
1"""A noisy check added to the job: every column named like an ID is personal. The platform decided otherwise for IDs2used for joining, so each owning team waives its findings, and the waiver count climbs. The prose's point rests on the3not-acted-on line of each check."""4from collections import Counter56from lib import ci78main = ci.checkout()9branch = ci.checkout(main) # the platform team adds the check to the job's settings10ci.edit(branch, "governance/ci.toml", '"properties"]', '"properties", "id-columns"]')11before, after = ci.build(main), ci.build(branch)1213report = ci.run(before, after)14print("waivers in the file, before:", len(ci.waivers(after.governance)))15noisy = next(check for check in report.checks if check.name == "id-columns")16print("job, before the waivers:", "passed" if report.passed else "failed")17print("id-columns, findings:", len(noisy.findings))18print("id-columns, findings on main:", len(noisy.on_main))19# the last word of each message is the classification20classified = Counter(finding.message.rpartition(" ")[2] for finding in noisy.findings)21for level, count in sorted(classified.items()):22 print(f"id-columns, findings classified {level}:", count)23# the part of the finding's ID after the check's name: the column's full name24print("id-columns, the public one:", ", ".join(f.id.split("/")[1] for f in noisy.findings if f.message.endswith("public")))2526with open(after.governance / "waivers.toml", "a", encoding="utf-8") as waivers:27 for finding in noisy.findings:28 waivers.write(f'\n[[waivers]]\nfinding = "{finding.id}"\nowner = "{finding.owner}"\n'29 'reason = "An ID for joining, internal by decision."\nexpires = 2026-10-31\n')3031report = ci.run(before, after)32print("waivers in the file, after:", len(ci.waivers(after.governance)))33print("job, with the waivers:", "passed" if report.passed else "failed")34for check in (check for check in report.checks if check.findings):35 idle = [f for f in check.findings if f.waiver or f.on_main] # findings nobody acted on36 print(f"{check.name}, not acted on:", f"{len(idle)} of {len(check.findings)} findings, {len(idle) / len(check.findings):.0%}: "37 f"{len(check.waived)} waived, {len(check.on_main)} on main")
python noisy-check-waivers.pywaivers in the file, before: 0
job, before the waivers: failed
id-columns, findings: 21
id-columns, findings on main: 0
id-columns, findings classified internal: 20
id-columns, findings classified public: 1
id-columns, the public one: learning.courses.course_id
waivers in the file, after: 21
job, with the waivers: passed
coverage, not acted on: 2 of 2 findings, 100%: 0 waived, 2 on main
properties, not acted on: 4 of 4 findings, 100%: 0 waived, 4 on main
id-columns, not acted on: 21 of 21 findings, 100%: 21 waived, 0 on main
このチェックは 21 個の列を検出するが、そのどれもプラットフォームが意図して分類した ID である。そのうち 20 個は internal であり、learning.courses.course_id は public である。
免除ファイルの免除は 0 件から 21 件に増え、ID チェックでは 21 of 21 findings, 100%: 21 waived, 0 on main となる。これは Tricorder の作者らが用いるどの閾値も超えている。ただし、彼らの指標は免除ではなくクリックを数えるため、これは類推にすぎない。プロパティのチェックも同じ割合の 4 of 4 findings, 100%: 0 waived, 4 on main を示すが、それは妥当である。その検出結果は、パイプラインの実行基盤に必要な修正だからである。件数だけでは両者を区別できないが、理由からは区別できる。
実践ルール: チェックを追加する前に、メインブランチで実行してすべての検出結果を読む。大半が免除されそうなら、検出結果を免除するのではなく、ルールを変更する。検出結果の大半が免除されたままのチェックは削除する。正しいチェックで免除の割合が高い場合は、担当者と期日を定めて取り組むべき作業として計画する。
壊れたファイルは指摘事項になる
サポート担当者のエントリが、引用符が欠けた状態で governance/users.toml に追加される。同じプルリクエストは、crm.learners.country を文字列型から数値型に変更しており、CRM チームがまだ分類していない work_email も含んでいる。
1"""A pull request that breaks two files the job reads: a support agent added to the users file with a quote missing,2and a migration Iceberg refuses. It also carries the CRM team's unclassified work_email column. The prose's point rests3on the two checks that could not run and on the exit code."""4from lib import ci56main = ci.checkout()7branch = ci.checkout(main)8# the closing quote after "support" is missing, so the users file no longer parses9ci.edit(branch, "governance/users.toml", '[users.agent-a09]', '[users.agent-a12]\ngroups = ["support]\nregion = "emea"\n\n'10 '[users.agent-a09]')11(branch / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")12# a string column cannot become an int: that isn't one of Iceberg's type promotions, so the migration is refused13(branch / "migrations" / "0002-country-as-number.sql").write_text("alter table crm.learners alter column country type int;\n")14print("files the pull request changes:", ", ".join(ci.changed(main, branch)))1516report = ci.run(main, branch)17for line in ci.lines(report):18 print(line)19print("checks that could not run:", ", ".join(check.name for check in report.checks if check.error))20print("checks that ran:", sum(check.error is None for check in report.checks))21print("exit code:", report.exit_code)
python broken-files-become-findings.pyfiles the pull request changes: governance/users.toml, migrations/0001-add-work-email.sql, migrations/0002-country-as-number.sql
coverage: failed, findings 3, new 1, on main 2, waived 0, 12 tables checked
contract-rules: passed, findings 0, new 0, on main 0, waived 0, 10 contracts checked
contracts: passed, findings 0, new 0, on main 0, waived 0, 11 files checked
policy-tests: failed, the check could not run
enforcement-tests: failed, the check could not run
migrations: failed, findings 1, new 1, on main 0, waived 0, 2 migrations checked
pipelines: passed, findings 0, new 0, on main 0, waived 0, 4 pipelines checked
lineage-classifications: passed, findings 0, new 0, on main 0, waived 0, 23 columns checked
owner-review: passed, findings 0, new 0, on main 0, waived 0, 77 columns checked
removals: passed, findings 0, new 0, on main 0, waived 0, 87 columns checked
properties: passed, findings 4, new 0, on main 4, waived 0, 12 tables checked
coverage/ai.review_corpus: no metadata; on main, owner team-platform
coverage/crm.learners.work_email: not classified; its name suggests personal
coverage/marketing.audience: no metadata; on main, owner team-platform
policy-tests/error: the check could not run: governance/users.toml doesn't parse: Illegal character '\n' (at line 13, column 20)
enforcement-tests/error: the check could not run: governance/users.toml doesn't parse: Illegal character '\n' (at line 13, column 20)
migrations/0002-country-as-number.sql: refused: Cannot change column type: country: string -> int
properties/ai.review_corpus: 7 of 7 generated properties missing; on main, owner team-platform
properties/analytics.course_performance: 4 of 4 generated properties missing; on main, owner team-analytics
properties/analytics.learner_activity: 4 of 4 generated properties missing; on main, owner team-analytics
properties/marketing.audience: 7 of 7 generated properties missing; on main, owner team-platform
change crm.learners, field 16: added as work_email string; named by 0 pipelines, reaches 0 columns
job: failed
checks that could not run: policy-tests, enforcement-tests
checks that ran: 9
exit code: 1
ユーザーファイルは、それを読む二つのチェックを壊す。結果は the check could not run: governance/users.toml doesn't parse: Illegal character '\n' (at line 13, column 20) である。Iceberg は、型昇格ではない型変更を refused: Cannot change column type: country: string -> int として拒否する。実行できなかった二つのチェックは、マイグレーションを含む他のチェックを止めない。そのため作成者は not classified; its name suggests personal も確認でき、ジョブは終了コード 1 で終了する。この捕捉がなければ、ジョブは最初のエラーで停止し、作成者は一回の実行につき一つの問題しか修正できない。
実践ルール: クラッシュしたチェックは、エラーの最初の行とそのエラーが示すファイルを添えた、ジョブを失敗させる一つの指摘事項に変換する。他のチェックはそれでも実行し、免除によってその指摘事項を黙らせてはならない。
その他の失敗
- 誰も必須にしなかったゲート。 ブランチ保護がステータスチェックを必須としていないジョブは、検出結果を報告しても、プルリクエストはそのままマージされる。このチェックを必須にし、ジョブが失敗したにもかかわらずマージされたプルリクエストを数える。
- 壊れたビルドは検出結果を隠す。 壊れたパイプラインが書き込まなかったテーブルは、説明のないテーブルとしても見つからない。まず
pipelinesのチェックを確認する。 - 免除は理由より長く残る。 検出結果が修正されても免除は残り、同じ ID を持つ次の検出結果を隠してしまうおそれがある。レポートは、どの検出結果にも一致しない免除を一覧にする。それらは削除する。
- 名前の変更は検出結果の ID を変える。 ID は列を指すため、名前を変更した列の検出結果は新しい ID で再び現れ、レポートはそれらの免除をどの検出結果にも一致しないものとして一覧にする。免除は、名前変更のプルリクエストの中で移す。
- 承認は、承認した内容より長く残る。
team-crmがcityのダウングレードを承認した後、作成者がemailのダウングレードをプッシュすると、その承認は両方に及んでしまう。ブランチ保護で「プルリクエストの差分に影響するコミットがプッシュされたとき、古くなったプルリクエストの承認を却下する」を有効にする。 - 1 件の承認がチーム全体を代弁する。 コードオーナーのうち 1 人の承認でも GitHub の要件は満たされ、ブランチ保護の件数はブランチ単位である。あるドメインがより多くの承認を求める場合は、ジョブの中でチームごとに承認を数える。
- ブロックされたチームがゲートを編集する。 プルリクエストが失敗したチームが、
ci.tomlからチェックを削除したり、免除を追加したり、CODEOWNERS を編集したりする。この 3 つすべてについて、プラットフォームチームをコードオーナーにする。 - プルリクエスト外の変更。 ノートブックがテーブルを作成したり、マイグレーションが手作業で実行されたりする。第 2 章が
problemsを実行するのと同じように、ジョブを本番環境に対しても定期的に実行する。
この章で決めたこと
- 1 つのジョブが、すべてのプルリクエストで第 2 章から第 7 章のチェックを実行する。 ジョブは
lib.ci.runであり、実行するチェックはgovernance/ci.tomlに列挙されている。第 3 章の値のサンプリングだけは、代わりにスケジュールで実行する。lib.ci.mainは終了コードを返し、レポートを Markdown として書き出す。 - ジョブは、プルリクエストが変更する内容を判定する。 プルリクエストが新たに持ち込む指摘は、承認または免除がない限りジョブを失敗させる。すでに main にある指摘は、その担当者とともに報告されるが、何も失敗させない。クラッシュしたチェックは、1 件の失敗する指摘として扱う。
- すべての指摘は安定した ID を持つ。 ID はチェックとその対象からなり、たとえば
coverage/crm.learners.work_emailである。 - プルリクエストは、スクラッチプラットフォーム上で main ブランチと比較する。 スクラッチプラットフォームは、プラットフォームが実際に動く方法で構築し、それぞれが独自のマイグレーションとパイプラインを持つ。
- スキーマの変更はフィールド ID で差分をとり、 3 通りに報告する。Iceberg のリーダー、SQL がその列を名指ししているパイプライン、そして INDIRECT エッジを含め、リネージが到達するとしているすべての列である。
- 独自のルールが 2 つある。 分類の引き下げ、担当者の変更、テーブルの別ドメインへの移動には、main ブランチ上のそのテーブルの担当者による承認が必要であり、承認はチーム単位で数える。また、列を削除できるのは、main ブランチがその列に
deprecatedの印を付けた後に限る。 - 所有関係は、テーブルごとの ODCS コントラクトで表す。 コントラクトは 1 つのドメインと、ロール
ownerの担当チームを持つ。コントラクトはドメインごとのフォルダに CODEOWNERS の行とともに生成され、ジョブが検査する。CODEOWNERS、ジョブの設定、グローバルルール、免除、マイグレーションは、プラットフォームチームが所有する。 - グローバルルールとドメインルールは Rego で書く。 すべてのコントラクトに対して regopy でインプロセス実行し、アクセスポリシーのフォルダの外に置く。
- 意図的に仕込んだギャップは main に残す。
marketing.audienceとai.review_corpusは、説明が書かれるまで、プラットフォームチームを担当者とするカバレッジの指摘として、すべてのレポートに現れる。 - ノイズは、チェックごとに、誰も対処しない指摘として測る。つまり免除された指摘か、main に残された指摘である。 指摘の大半が無視されるチェックは、チェックが誤っているか、プラットフォームが誤っているかのどちらかであり、件数だけではどちらかは分からない。免除は、1 件の指摘、担当者、理由、そして 90 日以内の終了日を指定する。カバレッジとエンフォースメントのテストは、決して免除しない。
- プルリクエストのチェックは、変更の大きさに合わせて規模を決める。 値を読むチェックはスケジュールで実行する。チェックは人々が有効にしている間しか役に立たないので、それぞれを変更の大きさに合わせて規模を決める。
この版における本章
第2026.11.31版2026年11月19日時点で例が通過この章の10 例件のうち10件が合格
英語版の書籍(版2026.11.31)から翻訳した。