Governance in CI

읽는 데 약 75분분 걸린다, 14절에 10개 예제이(가) 있음.

2026.11.31판 예제 통과 2026년 11월 19 108개 예제 중 108개 통과 변경 사항

AI로 번역함. 영어 원문을 사람이 검증함. 우리가 책을 만드는 방식

영어판 2026.11.31판을 번역한 것이다. 원문 읽기

이 부분은 아직 번역되지 않았으므로 영어로 표시된다.

By the end of this chapter you can run the governance checks of chapters 2 to 7 as one job on each pull request, judging only what the pull request changes. It fails when a column has no classification, runs the tests of the access policy and the enforcement layer, reports what each schema change reaches downstream, and enforces two rules that breaking-change checkers, the tools that compare two versions of a schema for changes that break its readers, don't. You'll keep ownership in contracts of the Open Data Contract Standard (ODCS), generated from the metadata, with a folder and a code owner per domain, layer each domain's rules on global ones, and measure each check's noise by the findings nobody acts on.

Earlier chapters built the governance checks of an online learning platform whose teams change its schemas every week, and no pull request runs any of them. Chapter 2 tests the catalog against the reviewed metadata, and chapter 4 reads lineage from every pipeline run. Chapter 5 tests the access policy, and chapter 6 tests the layer that enforces it on queries. Chapter 7 generates table properties from the classifications. Each runs only when someone runs its example, never when a team changes the platform. Three changes are on their way. The CRM team wants a column for learners' work email, the learning team wants to rename a column the reporting pipelines read, and the data-science team wants to see learners' cities without a mask. Each is a small diff a reviewer would approve, and each changes what breaks or who sees what.

This chapter adds the book's shared module for catching them, lib.ci, which is the platform's governance job. In this chapter the job is this CI job, not an OpenLineage one. Each simulated pull request runs offline, as two folders called checkouts, one of the main branch and one of the pull request's branch. Each holds governance/, the platform's governance files; pipelines/, its pipelines' SQL; migrations/, the alter table statements a branch changes schemas with, which lib.ci.migrate applies as Iceberg schema changes; and the files generated from the metadata. For each side, lib.ci.build builds a scratch platform the way the platform runs: the source tables, the side's migrations, the deploy, which writes the metadata into the catalog and sets every table's generated properties, then the nightly run of the side's own pipelines, with lineage. Among those pipelines, review_corpus stays chapter 4's ungoverned copy, so the job keeps checking its lineage; the platform trains on chapter 9's governed build. lib.ci.run runs the checks and compares the two sides. No git or network is involved, and every date is compared with the book's "today", Oct 1, 2026, never the clock.

이 부분은 아직 번역되지 않았으므로 영어로 표시된다.

Run every check as one job

마지막으로 변경된 판: 2026.11.27판

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.ci writes it as the check and the subject, such as coverage/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:

governance-ci-report.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 통과
"""The platform's governance job on one pull request, run as a CI step runs it: the CRM team adds a work email tocrm.learners. The prose's point rests on the coverage finding for the new column and on the exit code the step returns."""from lib import cifrom lib.platform import scratchmain = ci.checkout()                      # the main branch: governance files, pipelines and the files generated from thembranch = ci.checkout(main)                # the pull request's branch, starting from main(branch / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")print("files the pull request changes:", ", ".join(ci.changed(main, branch)))# What a CI step runs, `python -m lib.ci MAIN BRANCH --summary FILE`: it prints the report and its totals, writes the# report as Markdown for the pull request, and exits with the code it returns.summary = scratch() / "summary.md"code = ci.main([str(main), str(branch), "--summary", str(summary)])     # 1 when a finding this pull request adds fails itprint("the step exits with:", code)print("the summary it writes for the pull request:")print(summary.read_text(encoding="utf-8"), end="")
출력python governance-ci-report.py
files 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.

커밋이 아니라 풀 리퀘스트를 관문으로 삼는다

마지막으로 변경된 판: 2026.11.27판

플랫폼의 작업은 CI에서 실행된다. 검사를 실행할 수 있는 또 다른 곳은 프리커밋 훅(pre-commit hook)이며, 커밋이 만들어지기 전에 작성자의 컴퓨터에서 실행된다. git 훅을 위한 프레임워크인 pre-commit은 보통 커밋이 변경하는 파일에 대해서만 훅을 실행하며, 이 프레임워크의 문서는 훅을 코드 리뷰 전에 단순한 문제를 잡아내는 수단으로 소개한다(pre-commit). 이는 파일 하나만 있으면 되는 검사에 알맞다. metadata.toml가 파싱되는지, 그리고 모든 분류가 네 가지 값 중 하나인지를 확인하는 검사가 그러한 예이다.

그러나 커버리지 검사에는 맞지 않는다. 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로 실행하며, 발견 사항마다 ID와 추가해야 할 내용을 한 줄씩 출력한다. 또한 리뷰어가 diff를 읽는 풀 리퀘스트에 올릴 보고서를 Markdown으로 작성한다. 요약을 게시하는 일과 풀 리퀘스트의 리뷰에서 승인을 읽어 오는 일은 CI 서비스의 몫이며 이 책의 범위를 벗어난다.

작업 규칙: 훅은 작성자의 컴퓨터에서 단일 파일을 빠르게 검사하는 데 사용하고, 풀 리퀘스트의 CI 작업을 관문으로 삼아 메인 브랜치의 브랜치 보호로 이를 필수로 지정한다. 모든 발견 사항은 대시보드에만 두지 말고 ID와 조치 방법을 갖춰 풀 리퀘스트 자체에 기록한다. 어떤 풀 리퀘스트와도 무관하게 변경되는 테이블을 위해, 이 검사들을 운영 카탈로그에 대해서도 일정에 따라 실행한다.

이 부분은 아직 번역되지 않았으므로 영어로 표시된다.

Report what a schema change reaches

마지막으로 변경된 판: 2026.11.27판

The CRM team's added column reached nothing downstream, but a rename does, and its three kinds of readers, Iceberg, SQL and the governance metadata, judge it differently. Iceberg readers find columns by field ID, and the spec says that "projection must be done using field ids" (Iceberg table spec, 1.12.0), so a renamed column still reads every file written before the rename. SQL finds columns by name, so the same rename breaks every query and pipeline that names the column. The platform's governance metadata is keyed by field ID, as chapter 2 decided, so a rename needs only the name beside the ID updated. The spec's valid primitive type promotions are int to long, float to double, and a decimal's precision, which may only widen, plus, in format v3, date to timestamp or timestamp_ns, and a column of type unknown to any type. Any other change means a new column.

Which SQL a change breaks is a lineage question, and chapter 4 answered it by walking the column graph. A review has to follow INDIRECT edges too, chapter 4's name for inputs that decide which rows an output holds rather than what its values are. OpenLineage's column lineage facet keeps a dataset list for column lineage that affects the whole dataset, through filtering, sorting, grouping, joining, window functions and the like (ColumnLineageDatasetFacet, 1.54.0). A column used only to join or group shapes every row it feeds, which a report of copied values misses. lib.ci.changes compares the two sides' schemas field ID by field ID. For every column the branch renames, retypes or removes, it walks the main branch's lineage graph: the pipelines whose SQL names the column, the columns whose values come from it, every column it can change, and the teams that own them.

Next comes the learning team's rename of learning.courses.category to subject, in a migration and in the metadata file. The same pull request also fixes the two pipelines that name the column:

schema-change-impact.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 통과
"""What the learning team's rename of learning.courses.category reaches, through Iceberg readers, SQL and lineage. Theprose'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."""import pyarrow.compute as pcfrom lib import ci, retentionmain = ci.checkout()branch = ci.checkout(main)(branch / "migrations" / "0001-rename-category.sql").write_text(    "alter table learning.courses rename column category to subject;\n")ci.edit(branch, "governance/metadata.toml", '3 = { name = "category", classification = "public"',        '3 = { name = "subject", classification = "public"')       # the same field ID, renamedbefore, after = ci.build(main), ci.build(branch)# matched by field ID, so the rename is one change, not a column dropped and another addedchange = next(c for c in ci.changes(before, after) if c.table == "learning.courses")print("change:", change.kind, "from", change.before, "to", change.after)print("field ID, before and after:", change.field_id)# read by the new name: Iceberg maps it to the same field ID as beforesubjects = after.catalog.load_table("learning.courses").scan(selected_fields=("subject",)).to_arrow()print("courses whose subject an Iceberg reader finds:", pc.count(subjects["subject"]).as_py())print("pipelines whose SQL names it:", ", ".join(change.jobs))for job, why in sorted(after.failed.items()):    print(f"pipeline {job}, on the branch:", why)print("columns whose values come from it:", len(change.values))for column in change.values:    print("  value of:", column)print("columns it can change, DIRECT and INDIRECT:", len(change.reached))# a column's table is the first two parts of its name, schema.table.columnprint("tables those columns are in:", ", ".join(sorted({".".join(c.split(".")[:2]) for c in change.reached})))print("owners the report goes to:", ", ".join(change.owners))print("tables on main:", len(retention.tables(before.catalog)))print("tables on the branch:", len(retention.tables(after.catalog)))coverage = ci.run(before, after, checks=["coverage"]).checks[0]print("coverage findings on the branch:", ", ".join(finding.id for finding in coverage.findings))# The same pull request, with both pipelines changed to read the new name. Each side runs its own pipelines/.ci.edit(branch, "pipelines/course_performance.sql", "    c.category,", "    c.subject as category,")ci.edit(branch, "pipelines/course_performance.sql", "c.title, c.category", "c.title, c.subject")sql = (branch / "pipelines" / "marketing_audience.sql").read_text(encoding="utf-8")(branch / "pipelines" / "marketing_audience.sql").write_text(sql.replace("c.category", "c.subject").replace(    "f.category", "f.subject"), encoding="utf-8")fixed = ci.build(branch)ci.generate(fixed)                        # and the contracts generated again, as the author's hook wouldprint("files the fixed pull request changes:", ", ".join(ci.changed(main, branch)))for line in ci.lines(ci.run(before, fixed, checks=["pipelines", "coverage", "contracts", "lineage-classifications"])):    print("with the fix,", line)
출력python schema-change-impact.py
change: 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

For Iceberg, nothing broke. The rename kept the column's field ID, so an Iceberg reader on the branch still finds a subject for 200 courses. For SQL, the pipelines that name the column, course_performance, marketing_audience, each stop before writing anything on the branch, because chapter 4 made unreadable lineage an error. Through values, the rename reaches 2 columns, the two copies of the category. Through every edge it reaches 12 columns, every column of analytics.course_performance, marketing.audience, because categories group the course report and rank each learner's favourite. The report goes to no owner, team-analytics: the analytics team, and nobody for marketing.audience, which has no owner yet.

A broken build hides what it breaks. The branch's catalog holds 10 tables, against 12 on main, because the broken pipelines wrote nothing. Coverage reports only coverage/ai.review_corpus: a table that doesn't exist can't be found undescribed, so marketing.audience's finding is gone. Each side runs its own pipelines/, so the fix travels with the rename: with both pipelines reading subject, the job reports passed. In production, the merge can also guard what the review saw. A REST catalog commit can carry AssertCurrentSchemaId, which requires the table's current schema ID to match the one the requirement names (REST catalog spec, 1.12.0), so a migration reviewed against one schema fails instead of applying to another.

Working rule: Diff schemas by field ID, never by name or schema ID, and report every rename, type change and removal three ways: whether Iceberg readers are affected, which pipelines' SQL names the column, and what it reaches through lineage, INDIRECT edges included. Send the report to the owners of every table it reaches. Merge a rename that breaks a pipeline in the same pull request as the pipeline's fix, never before it.

분류를 낮추기 전에 소유자에게 물어라

마지막으로 변경된 판: 2026.11.27판

호환성 파괴 변경 검사기는 스키마의 독자(소비자)를 보호한다. dbt의 모델 계약은 열을 제거하거나 열의 데이터 타입을 바꾸는 일을 하위 소비자에게 영향을 줄 수 있는 호환성 파괴 변경으로 표시한다(dbt 모델 계약). datacontract-cli의 breaking 명령은 ODCS 계약 두 개를 비교하고, 소비자가 의존하는 보장을 깨뜨리는 변경이 있으면 실패 처리한다(datacontract-cli 1.2.7). 그러나 둘 다 보호를 보장으로 다루지는 않는다. datacontract-cli 1.2.7에는 속성의 분류나 팀 구성원의 역할을 다루는 규칙이 없으므로, 둘 중 어느 하나가 바뀌면 검증되지 않음으로 표시하는 규칙이 적용된다(rules.py). 탐지기는 이런 변경을 INFO 수준으로 보고하는데(detector.py), 이 수준은 실패로 처리되지 않는다. 이 명령은 ERROR 항목이 있을 때만 종료 코드 1로 끝난다(breaking 명령 구현, breaking 모델 정의). examples/requirements.txt는 이 버전을 고정하지 않으므로 어떤 예제도 이 명령을 실행하지 않는다. 2026년 10월 22일에 datacontract-cli 1.2.7을 이 장에서 crm.learners용으로 생성한 계약에 실행했더니, 이름이 바뀐 email에 대해 종료 코드 1로 실패했다. 이 도구는 속성을 이름으로 대응시키므로(normalize.py), 속성이 id를 그대로 유지했는데도 이름 변경을 제거로 읽었다. 반면 email의 분류를 personal에서 public로 바꾼 변경과 소유자 변경은 종료 코드 0으로 통과시켰다. ODCS 자체도 분류에는 "무엇이든 올 수 있다"고 밝힌다(ODCS v3.2.0 스키마).

그런데 모든 정책이 분류를 읽으므로, 분류를 낮추는 일은 메타데이터 파일이 담을 수 있는 변경 가운데 가장 파급이 큰 축에 속한다. 우리는 첫 번째 규칙을 직접 추가한다. 열의 분류를 낮추거나, 테이블의 소유자를 바꾸거나, 테이블을 다른 도메인으로 옮기려면 main 브랜치에서 그 테이블을 소유한 팀의 승인을 받아야 한다. 도메인 고유의 규칙이 그 도메인의 테이블에 적용되므로(뒤의 절), 도메인 이동은 소유권 변경으로 센다. 소유자는 main 브랜치에서 가져온다. 그렇지 않으면 풀 리퀘스트가 테이블을 새 소유자에게 넘기고, 그 새 소유자가 분류 하향을 승인할 수 있기 때문이다. 2장은 모델의 초안에 같은 규칙을 정했다. 분류를 낮추는 일은 검토자만 할 수 있고, 그 이유는 열의 설명에 적는다.

데이터 과학 팀의 풀 리퀘스트가 마지막이다. 이 풀 리퀘스트는 데이터 과학자가 학습자를 도시별로 묶을 수 있도록 crm.learners.city의 분류를 personal에서 internal로 낮춘다. 접근 정책은 데이터 과학자에게 개인 열을 가명 처리하는데, 이 하향으로 city가 그 규칙에서 빠진다. 실행은 변경 전과 후에 정책에 질의하고, 스키마와 정책을 보는 검사와 소유자 규칙을 차례로 실행한다.

classification-downgrade.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 통과
"""A pull request from the data-science team lowers crm.learners.city from personal to internal. The prose's point restson analyst-1's mask on each side, and on the owner rule failing alone."""from lib import ci, policymain = ci.checkout()branch = ci.checkout(main)ci.edit(branch, "governance/metadata.toml", '6 = { name = "city", classification = "personal"',        '6 = { name = "city", classification = "internal"')before, after = ci.build(main), ci.build(branch)reading_city = policy.request("analyst-1", "crm.learners", ["learner_id", "city"])for side, name in ((before, "main"), (after, "the branch")):    rego = policy.interpreter(side.governance / "policies", data=ci.policy_data(side))    # a column with no mask in the decision is shown as it is stored    print(f"analyst-1 reading city, on {name}:", policy.decide(reading_city, rego)["column_masks"].get("city", "unmasked"))checks = ["policy-tests", "enforcement-tests", "removals", "owner-review"]report = ci.run(before, after, checks=checks)print("schema changes:", len(report.changes))for line in ci.lines(report):    print(line)# The approvals come from the pull request's reviews: one entry per approving review, named by the reviewer's team.# The owner rule passes when it raises no unapproved finding.owner_review = lambda approvals: "passed" if ci.run(before, after, approvals, checks=["owner-review"]).passed else "failed"print("owner-review, once team-crm approves:", owner_review(["team-crm"]))print("owner-review, once team-analytics approves:", owner_review(["team-analytics"]))ci.edit(after.root, "governance/ci.toml", "teams = {}", "teams = { team-crm = 2 }")     # team-crm asks for two# one approval from team-crm and one from another team: team-crm still needs a second of its ownprint("owner-review, two required, one from team-crm:", owner_review(["team-crm", "team-platform"]))print("owner-review, two required, two from team-crm:", owner_review(["team-crm", "team-crm"]))
출력python classification-downgrade.py
analyst-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

메타데이터 파일의 단어 하나가 한 역할 전체에 대해 열의 마스킹을 해제하지만, 소유자 규칙 외에는 어떤 검사도 이를 알아차리지 못한다. 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에서 실패한다.

소유자 규칙을 해소하는 것은 소유자의 승인이다. 승인은 승인한 검토마다 항목 하나씩, 검토자의 팀 이름을 붙여 lib.ci.run에 전달된다. team-crm의 승인이 있으면 소유자 규칙은 passed를 보고하고, 이 테이블을 소유하지 않은 team-analytics의 승인이 있으면 failed를 보고한다.

작업 규칙: 분류를 낮추는 일, 소유자를 바꾸는 일, 다른 도메인으로 옮기는 일은 main 브랜치 기준 테이블 소유자의 승인이 필요한 변경으로 다루고, 승인이 주어질 때까지 작업을 실패시킨다. 이런 변경을 호환성 파괴 변경 검사기에 맡겨서는 안 된다. 같은 풀 리퀘스트에서 열의 설명에 이유를 적도록 요구한다. 분류를 높이는 일은 숨기는 범위만 넓힐 뿐이므로 이런 승인이 필요하지 않다.

이 부분은 아직 번역되지 않았으므로 영어로 표시된다.

Deprecate a column before removing it

마지막으로 변경된 판: 2026.11.31판

The owner rule guards a change that breaking-change checkers ignore. Removing a column is the change they all catch, but by then the removal is already under review, too late to help the readers it breaks. ODCS 3.2.0 adds a way to warn readers first. Any element of a contract, a schema object or a property, nested ones included, may set the optional deprecated boolean to signal that it is no longer recommended for use. The standard also asks that the description point to a replacement and give migration guidance (ODCS v3.2.0 schema). Our second rule makes the deprecation warning a required step: a column may leave a table only once the main branch has marked it deprecated. That takes two pull requests, one that deprecates the column and one that removes it, and the column's readers have the time between them to move off it.

The platform's metadata file had no such field, so this chapter adds one: deprecated = true in a column's entry. lib.metadata.load reads it as Column.deprecated, false when it's absent, and lib.ci.contract writes it into the column's contract as ODCS's deprecated.

The platform's best candidate is billing.payments.card_number. Its own description says it "Should not be stored at all", and chapter 3 found that it holds full card numbers. team-billing removes it twice, each time by dropping the column in a migration and deleting its metadata entry: once straight away, and once after a pull request that deprecates it has merged:

deprecate-then-remove.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 통과
"""team-billing removes the legacy card_number column from billing.payments: once straight away, and once after a pullrequest that deprecates it has merged. The prose's point rests on the two removal lines."""import yamlfrom lib import cientry = ('8 = { name = "card_number", classification = "sensitive", '         'description = "The full card number, from a legacy export. Should not be stored at all." }\n')# the note goes after the description's sentence ending "at all.", and deprecated = true goes inside the entry's bracesdeprecated_entry = entry.replace("all.", "all. Deprecated: reconcile payments by payment_id.").replace(" }", ", deprecated = true }")def remove_card_number(base, line):    """A pull request on top of `base` that drops the column and deletes its metadata entry."""    branch = ci.checkout(base)    (branch / "migrations" / "0001-drop-card-number.sql").write_text("alter table billing.payments drop column card_number;\n")    ci.edit(branch, "governance/metadata.toml", line, "")    return branchmain = ci.checkout()deprecated = ci.checkout(main)            # the first pull request: mark the column deprecated, and say what replaces itci.edit(deprecated, "governance/metadata.toml", entry, deprecated_entry)for base, line, name in ((main, entry, "straight away"), (deprecated, deprecated_entry, "after the deprecation merged")):    report = ci.run(ci.build(base), ci.build(remove_card_number(base, line)), checks=["removals"])    print(f"removal, {name}:", "passed" if report.checks[0].passed else "failed")    for finding in report.checks[0].findings:        print(f"  {finding.id}:", finding.message)# property 7 is the eighth column, field 8: card_number, the column the deprecation markscard_number = ci.contract(ci.build(deprecated), "billing.payments")["schema"][0]["properties"][7]print("the deprecated column in its ODCS contract:")print(yaml.safe_dump(card_number, sort_keys=False, width=200), end="")
출력python deprecate-then-remove.py
removal, 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

Straight away, the removal fails, removed without being deprecated on the main branch first. After the deprecation has merged, the same removal reports passed. In between, the contract carried the warning to everyone who reads contracts, not only to the repository: deprecated: true, with a description that says how to reconcile payments without the column. The rule checks the order of the two changes, not the time between them. How long readers get is a decision for the owning team and the column's readers, and the impact report says who those readers are.

Working rule: Remove a column in two pull requests: first mark it deprecated, with its replacement in the description, and merge that; then drop it from the table and its entry from the metadata. Fail any removal of a column the main branch hadn't deprecated. Agree with the column's readers how long the deprecation lasts, since the job checks only that it came first.

이 부분은 아직 번역되지 않았으므로 영어로 표시된다.

Route each domain's reviews by path

마지막으로 변경된 판: 2026.11.31판

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:

domain-contracts.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 통과
"""Ownership as ODCS contracts, a folder per domain, and who GitHub asks to review the downgrade of crm.learners.citywhen the metadata is one shared file, and when each domain has a folder of contracts generated from it. The prose'spoint rests on the first review line and on the contracts check failing before the files are generated again."""import yamlfrom lib import cimain = ci.checkout()                      # the main branch holds the contracts and CODEOWNERS generated from its metadatabranch = ci.checkout(main)ci.edit(branch, "governance/metadata.toml", '6 = { name = "city", classification = "personal"',        '6 = { name = "city", classification = "internal"')shared = ["/governance/ @example-org/team-platform"]          # one file for every domain, owned by the platform teamfor path, owners in ci.reviewers(shared, ["governance/metadata.toml"]).items():    print(f"one shared file, review of {path}:", " ".join(owners))crm = yaml.safe_load((main / "governance/contracts/crm/learners.odcs.yaml").read_text(encoding="utf-8"))print(yaml.safe_dump({"domain": crm["domain"], "team": crm["team"]}, sort_keys=False), end="")lines = (main / ".github/CODEOWNERS").read_text(encoding="utf-8").splitlines()for line in lines[1:]:                                       # the first line says the file is generated    print("CODEOWNERS", line)before, after = ci.build(main), ci.build(branch)          # the pull request changes the metadata onlyprint("teams that own tables:", len({table.owner for table in before.described.values()}))# drops the job's verdict, the last line, which this example doesn't printfor line in ci.lines(ci.run(before, after, checks=["contracts"]))[:-1]:    print("before generating again,", line)print("files generated again:", len(ci.generate(after)))print("after generating again, contracts:", "passed" if ci.run(before, after, checks=["contracts"]).passed else "failed")# the last matching CODEOWNERS line wins, as GitHub applies itfor path, owners in ci.reviewers(lines, ci.changed(main, branch)).items():    print(f"a folder per domain, review of {path}:", " ".join(owners))
출력python domain-contracts.py
one 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.

이 부분은 아직 번역되지 않았으므로 영어로 표시된다.

Layer domain rules on the global rules

마지막으로 변경된 판: 2026.11.31판

Teams that own their domains' contracts still share one platform, and some rules have to hold in every domain. Dehghani's description of data mesh calls this federated computational governance, "a set of global rules - rules applied to all data products and their interfaces - to ensure a healthy and interoperable ecosystem". Those global rules sit beside the decisions each domain makes for itself, and the platform executes both (Dehghani, 2020). That's a framing, not a measurement, and it maps onto code. The platform team keeps one package of global rules, which the domains agree on, and in Dehghani's version the domain and platform product owners together decide them. Each domain has a package of its own, owned by its team, and one job runs them all.

The OPA project's tool for rules over files is Conftest, which tests structured configuration data with Rego (Conftest). lib.ci runs the same kind of rules in-process with regopy, as chapter 5 runs the access policy. governance/ci/global.rego holds the global rules: one owner, whatever the case of its role; one domain, which a missing, empty or blank value fails, since an empty string is a defined value in Rego and not alone would pass it; a classification from the four, since ODCS accepts any string; and a description for every column. governance/ci/domains/crm.rego holds team-crm's rule: nothing in crm is public, because everything in it describes a learner or an instructor. The contract-rules check runs the global package on every contract, and each domain's package on the contracts of that domain on the branch. A rule returns each violation as data, with the rule's name, a subject and a message. A violation's subject and the rule's name make the finding's ID. These files sit outside governance/policies/, the access policy's folder, so changing them never changes the policy revision that chapter 8 records with every decision.

The CRM team's change comes back, this time with metadata. work_email is classified public, on the argument that a work address is business information, and its description is empty. The second try adds a description and moves crm.learners to the analytics domain, which has no rules of its own:

global-and-domain-rules.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 통과
"""The platform's global rules and the crm domain's own rule, run on the CRM team's two tries at work_email: classifiedpublic with no description, then described with crm.learners moved to the analytics domain, which has no rules of its own.The prose's point rests on the two contract-rules findings of the first try and on the owner-review finding after the move."""from lib import cimain = ci.checkout()branch = ci.checkout(main)(branch / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")ci.edit(branch, "governance/metadata.toml", '15 = { name = "notes"',        '16 = { name = "work_email", classification = "public", description = "" }\n15 = { name = "notes"')for path in sorted((branch / "governance" / "ci").rglob("*.rego")):    print("rules:", path.relative_to(branch).as_posix())before = ci.build(main)report = ci.run(before, branch, checks=["coverage", "contract-rules"])for line in ci.lines(report):    print(line)# The second try: a description, and the table moved to a domain whose rules allow public columns.ci.edit(branch, "governance/metadata.toml", 'description = "" }', 'description = "The learner\'s work address." }')# the table's domain changes from crm to analytics, which has no rules of its ownci.edit(branch, "governance/metadata.toml", 'owner = "team-crm"\ndomain = "crm"\ndescription = "Every learner',        'owner = "team-crm"\ndomain = "analytics"\ndescription = "Every learner')report = ci.run(before, branch, checks=["coverage", "contract-rules", "owner-review"])for line in ci.lines(report):    print("moved to analytics,", line)
출력python global-and-domain-rules.py
rules: 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

Coverage flags the classification now: classified public; its name suggests personal; needs team-crm's approval. A name is evidence, and a pull request has no values to read, so a classification below the name's suggestion is a finding only the owner on main can answer.

The contract rules ask more. The global package flags no description (global rule described), and the crm package flags crm classifies no column public (domains.crm rule no-public). team-crm decided the second rule without asking any other team, and the platform runs it for them on every pull request, including pull requests from team-crm.

On the second try, the analytics domain's rules apply, and the contract rules pass: passed, findings 0, new 0, on main 0, waived 0, 10 contracts checked. The move itself fails, on domain changed from crm to analytics; needs team-crm's approval, and so does the classification.

Working rule: Write the rules every domain must follow as one global package, kept by the platform team, and let each domain add a package of its own, owned by its team, that runs on that domain's contracts only. Return violations as data with a stable subject, never as a bare pass or fail. Let domain rules add to the global rules, never replace them, and treat a table's move to another domain as an ownership change, so no team escapes its domain's rules by changing one word.

검사별로 면제된 발견 사항 세기

마지막으로 변경된 판: 2026.11.27판

지금까지의 검사는 각각 나름의 이유로 풀 리퀘스트를 실패시킨다. 게이트는 사람들이 더 이상 믿지 않을 때도 실패한다. Google의 Tricorder 저자들은 사용자가 조치하지 않기로 선택한 모든 보고를 사실상의 오탐으로 정의하며, 코드 리뷰 단계에서 이 비율을 10% 미만으로 유지한다. 실제로 조치하는 대상은 이보다 좁은 not-useful 비율이다. 이는 분석기에 대한 Not useful 클릭이 Not useful, Please fix, Apply fix 클릭 전체에서 차지하는 비율이다. 이 비율이 10% 이상이면 분석기는 유예 상태에 들어가고, 25%를 넘으면 즉시 꺼질 수 있다(Sadowski et al., 2015). 이는 한 회사의 코드 분석 사례이고 임곗값도 그 회사가 직접 정한 것이며, 데이터 거버넌스에 대응하는 공개된 기준은 알려진 바 없다. 이 척도는 유추로서 적용할 수 있다. 검사마다 아무도 조치하지 않은 발견 사항을 세는데, 면제된 것과 main에 남겨진 것을 모두 센다.

플랫폼에서 새 발견 사항에 조치하지 않기로 하는 결정이 면제(waiver)이다. governance/waivers.toml의 면제는 발견 사항 하나를 ID로 지정하고, 그에 책임이 있는 팀, 사유, 적용되는 마지막 날을 적는다. lib.ci는 작업이 실행되는 날로부터 최대 90일까지 유지되는 면제만 받아들인다. 이 한도는 governance/ci.toml에 두는 경험칙이며, 이에 따라 모든 면제는 결정을 위해 다시 돌아온다. 같은 파일에는 날짜와 상관없이 어떤 면제로도 막을 수 없는 검사도 나열되어 있다. 하나는 커버리지로, 소유자가 없는 테이블이나 분류가 없는 열은 풀 리퀘스트에서 고치기 때문이다. 다른 하나는 강제 적용 테스트이다. 이미 main에 있는 발견 사항에는 면제가 필요 없다. 만료된 면제는 아무것도 막지 않으며, 보고서에 그 면제가 나열된다. 면제 파일은 플랫폼 팀이 소유하므로 각 면제도 검토를 거치는 변경이다.

CRM 변경에는 면제가 두 개 필요하다. 첫 번째는 분류되지 않은 열을 다룬다. 두 번째는 열을 personal로 분류한 뒤에도 아직 작성하지 않은 설명을 다룬다. 팀은 두 번째 면제를 처음에는 여름까지, 다음에는 10월 31일까지 적용해 달라고 요청한다:

waived-findings.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 통과
"""Waivers on the CRM team's pull request: one for the unclassified work_email column, which coverage never allows;then, with the column classified but not yet described, one that asks for too long, and one that fits, on the book'stoday and a month later. The prose's point rests on the two refusals and on the expired waiver the report lists."""from datetime import datefrom lib import cifrom lib.platform import TODAYdef waive(branch, finding, expires, reason):    with open(branch / "governance" / "waivers.toml", "a", encoding="utf-8") as waivers:        # the date is written unquoted, so TOML reads it as a date, which the job compares with the day it runs        waivers.write(f'\n[[waivers]]\nfinding = "{finding}"\nowner = "team-crm"\nreason = "{reason}"\nexpires = {expires}\n')main = ci.checkout()before = ci.build(main)unclassified = ci.checkout(main)(unclassified / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")waive(unclassified, "coverage/crm.learners.work_email", "2026-10-31", "Classified once the sign-up form is live.")for line in ci.lines(ci.run(before, unclassified, checks=["coverage"])):    print("unclassified,", line)undescribed = ci.checkout(main)          # the second try: classified, with its description still to come(undescribed / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")ci.edit(undescribed, "governance/metadata.toml", '15 = { name = "notes"',        '16 = { name = "work_email", classification = "personal", description = "" }\n15 = { name = "notes"')waive(undescribed, "contract-rules/crm.learners.work_email/described", "2027-06-30", "Described once the form's copy is final.")after = ci.build(undescribed)for line in ci.lines(ci.run(before, after, checks=["coverage", "contract-rules"])):    print("undescribed, asked until 2027-06-30,", line)# the same waiver, shortened to the end of October, within the longest a waiver may runci.edit(undescribed, "governance/waivers.toml", "2027-06-30", "2026-10-31")for day in (TODAY, date(2026, 11, 1)):    # the book's today, then a month later, after the waiver has expired    report = ci.run(before, after, today=day, checks=["coverage", "contract-rules"])    print(f"undescribed, asked until 2026-10-31, on {day}, contract-rules:", "passed" if report.checks[1].passed else "failed")    print(f"undescribed, asked until 2026-10-31, on {day}, findings waived:", sum(len(c.waived) for c in report.checks))    print(f"undescribed, asked until 2026-10-31, on {day}, waivers that silence nothing:",          "; ".join(why for _, why in report.unused) or "none")
출력python waived-findings.py
unclassified, 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

분류되지 않은 열에 대한 면제는 한 달만 요청했는데도 거부된다. 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이다. 날짜는 지나갔지만 문제는 사라지지 않았다.

작업 규칙: 면제는 풀 리퀘스트가 새로 만드는 발견 사항 정확히 하나를 지정하게 하고, 책임 팀, 사유, 길어야 몇 달 뒤인 종료일을 함께 적게 한다. 분류나 소유자 누락처럼 어떤 면제로도 막아서는 안 되는 검사는 목록으로 둔다. 검사마다 아무도 조치하지 않은 발견 사항이 몇 건인지 면제된 것과 main에 남겨진 것을 모두 보고하고, 그 대부분이 여기에 해당하는 검사는 검토한다. 검사가 잘못되었거나 플랫폼이 잘못되었거나 둘 중 하나인데, 이 수치만으로는 어느 쪽인지 알 수 없다.

운영 환경에서 무엇이 잘못되는가

마지막으로 변경된 판: 2026.11.27판

우리의 판단으로는 거버넌스 작업은 고장 나는 경우보다 꺼지는 경우가 더 많다. 팀은 느리거나 잡음이 많은 검사를 governance/ci.toml에서 한 줄씩 제거하고, 게이트는 지키는 범위가 줄어드는 가운데에도 계속 통과한다. 단계적으로 구성한 두 검사를 통해 그 과정을 보이는데, 시간 대신 개수를 사용한다. 세 번째 사례는 고장 나는 작업을 보여 준다.

이 부분은 아직 번역되지 않았으므로 영어로 표시된다.

A check that reads every row

마지막으로 변경된 판: 2026.11.27판

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:

slow-check-every-row.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 통과
"""The support team's pull request adds two columns to support.tickets, which coverage judges by their names and chapter3's value checks judge by reading a sample, or every row. The prose's point rests on the callback number's empty columnand on the values each check reads; counts of values stand in for time, which depends on the machine."""import pyarrow as pafrom lib import ci, piimain = ci.checkout()branch = ci.checkout(main)(branch / "migrations" / "0001-callback-and-reply.sql").write_text(    "alter table support.tickets add column callback_number varchar;\n"    "alter table support.tickets add column reply_email varchar;\n")ci.edit(branch, "governance/metadata.toml", '8 = { name = "status"',        '9 = { name = "callback_number", classification = "internal", description = "A number to call the learner back on." }\n'        '10 = { name = "reply_email", classification = "public", description = "Where the reply goes." }\n8 = { name = "status"')before, after = ci.build(main), ci.build(branch)report = ci.run(before, after, checks=["coverage", "classify-sampled", "classify-every-row"])for name in ("body", "callback_number", "reply_email"):    values = after.catalog.load_table("support.tickets").scan(selected_fields=(name,)).to_arrow()[name]    print(f"support.tickets.{name}, values on the branch:", f"{len(values) - values.null_count:,}")    for check in report.checks:        found = [f.message for f in check.findings if f.id == f"{check.name}/support.tickets.{name}"]        print(f"support.tickets.{name}, {check.name}:", found[0] if found else "no finding")for check in report.checks[1:]:    print(f"{check.name}, values read:", f"{check.checked:,}")text_columns, sampled, every_row = 0, 0, 0for name in sorted(before.described):    data = before.catalog.load_table(name).scan().to_arrow()    # the non-null values of each text column, the ones a value check classifies    filled = [len(column) - column.null_count for column in data.columns if pa.types.is_string(column.type)]    text_columns += len(filled)    # the sampled check reads at most pii.ROWS values of each column    sampled += sum(min(pii.ROWS, count) for count in filled)    every_row += sum(filled)print("text columns in the described tables:", text_columns)print("values the sampled check would read in them:", f"{sampled:,}")print("values the every-row check would read in them:", f"{every_row:,}")
출력python slow-check-every-row.py
support.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에 경고를 내는 검사

마지막으로 변경된 판: 2026.11.27판

신중한 한 팀이 ID처럼 이름 붙은 모든 열을 개인 데이터로 취급하는 검사를 추가한다. 그러나 플랫폼은 조인에 쓰는 ID에 대해 다르게 결정했다. 2장은 learner_id를 internal로 분류하고, 이를 해석하는 테이블을 보호한다. 이 검사의 결과는 새로 나온 것이므로, 각 담당 팀이 이를 면제 처리한다.

noisy-check-waivers.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 통과
"""A noisy check added to the job: every column named like an ID is personal. The platform decided otherwise for IDsused for joining, so each owning team waives its findings, and the waiver count climbs. The prose's point rests on thenot-acted-on line of each check."""from collections import Counterfrom lib import cimain = ci.checkout()branch = ci.checkout(main)                          # the platform team adds the check to the job's settingsci.edit(branch, "governance/ci.toml", '"properties"]', '"properties", "id-columns"]')before, after = ci.build(main), ci.build(branch)report = ci.run(before, after)print("waivers in the file, before:", len(ci.waivers(after.governance)))noisy = next(check for check in report.checks if check.name == "id-columns")print("job, before the waivers:", "passed" if report.passed else "failed")print("id-columns, findings:", len(noisy.findings))print("id-columns, findings on main:", len(noisy.on_main))# the last word of each message is the classificationclassified = Counter(finding.message.rpartition(" ")[2] for finding in noisy.findings)for level, count in sorted(classified.items()):    print(f"id-columns, findings classified {level}:", count)# the part of the finding's ID after the check's name: the column's full nameprint("id-columns, the public one:", ", ".join(f.id.split("/")[1] for f in noisy.findings if f.message.endswith("public")))with open(after.governance / "waivers.toml", "a", encoding="utf-8") as waivers:    for finding in noisy.findings:        waivers.write(f'\n[[waivers]]\nfinding = "{finding.id}"\nowner = "{finding.owner}"\n'                      'reason = "An ID for joining, internal by decision."\nexpires = 2026-10-31\n')report = ci.run(before, after)print("waivers in the file, after:", len(ci.waivers(after.governance)))print("job, with the waivers:", "passed" if report.passed else "failed")for check in (check for check in report.checks if check.findings):    idle = [f for f in check.findings if f.waiver or f.on_main]          # findings nobody acted on    print(f"{check.name}, not acted on:", f"{len(idle)} of {len(check.findings)} findings, {len(idle) / len(check.findings):.0%}: "          f"{len(check.waived)} waived, {len(check.on_main)} on main")
출력python noisy-check-waivers.py
waivers 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를 보이며, 그럴 만하다. 그 검사의 결과는 파이프라인 실행기에 필요한 수정이기 때문이다. 개수만으로는 두 검사를 구별할 수 없지만, 이유를 보면 구별할 수 있다.

작업 규칙: 검사를 추가하기 전에 main 브랜치에서 실행하여 모든 결과를 읽는다. 대부분이 면제될 것이라면 결과를 면제하지 말고 규칙을 바꾼다. 결과 대부분이 계속 면제되는 검사는 제거하고, 올바른 검사에서 높은 비율이 나오면 담당자와 기한을 정해 일정에 넣을 작업으로 취급한다.

깨진 파일은 발견 사항이 된다

마지막으로 변경된 판: 2026.11.27판

지원 담당자의 항목이 따옴표 하나가 빠진 채 governance/users.toml에 들어간다. 같은 풀 리퀘스트는 crm.learners.country의 타입을 텍스트에서 숫자로 바꾸며, CRM 팀이 아직 분류하지 않은 work_email도 함께 들어 있다.

broken-files-become-findings.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 · tldextract 5.4.0 통과
"""A pull request that breaks two files the job reads: a support agent added to the users file with a quote missing,and a migration Iceberg refuses. It also carries the CRM team's unclassified work_email column. The prose's point restson the two checks that could not run and on the exit code."""from lib import cimain = ci.checkout()branch = ci.checkout(main)# the closing quote after "support" is missing, so the users file no longer parsesci.edit(branch, "governance/users.toml", '[users.agent-a09]', '[users.agent-a12]\ngroups = ["support]\nregion = "emea"\n\n'        '[users.agent-a09]')(branch / "migrations" / "0001-add-work-email.sql").write_text("alter table crm.learners add column work_email varchar;\n")# a string column cannot become an int: that isn't one of Iceberg's type promotions, so the migration is refused(branch / "migrations" / "0002-country-as-number.sql").write_text("alter table crm.learners alter column country type int;\n")print("files the pull request changes:", ", ".join(ci.changed(main, branch)))report = ci.run(main, branch)for line in ci.lines(report):    print(line)print("checks that could not run:", ", ".join(check.name for check in report.checks if check.error))print("checks that ran:", sum(check.error is None for check in report.checks))print("exit code:", report.exit_code)
출력python broken-files-become-findings.py
files 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로 끝난다. 이렇게 오류를 잡아내지 않으면 작업은 첫 번째 오류에서 멈추고, 작성자는 실행할 때마다 문제를 하나씩만 고치게 된다.

작업 규칙: 비정상 종료하는 검사는 오류의 첫 줄과 그 오류가 가리키는 파일을 담아 작업을 실패시키는 발견 사항 하나로 바꾼다. 다른 검사도 그대로 실행하며, 면제로 이 발견 사항을 무시하게 해서는 안 된다.

그 밖의 실패

마지막으로 변경된 판: 2026.11.27판
  • 아무도 요구하지 않은 게이트. 브랜치 보호가 상태 검사를 요구하지 않는 작업은 결과를 보고하지만, 풀 리퀘스트는 그대로 병합된다. 해당 검사를 필수로 지정하고, 작업이 실패했는데도 병합된 풀 리퀘스트를 집계한다.
  • 빌드가 깨지면 결과가 가려진다. 깨진 파이프라인이 쓰지 못한 테이블은 설명이 없는 상태로도 발견되지 않는다. 먼저 pipelines 검사를 확인한다.
  • 면제는 사유보다 오래 남는다. 결과가 수정되어도 면제는 남아 있어, 같은 ID를 가진 다음 결과를 가릴 수 있다. 보고서는 어떤 결과와도 일치하지 않는 면제를 나열하므로, 그 면제를 삭제한다.
  • 이름을 바꾸면 결과 ID가 바뀐다. ID는 열을 가리키므로, 이름이 바뀐 열의 결과는 새 ID로 다시 나타나고, 보고서는 그 면제를 어떤 결과와도 일치하지 않는 것으로 나열한다. 이름을 바꾸는 풀 리퀘스트에서 면제도 함께 옮긴다.
  • 승인은 승인 대상보다 오래 남는다. team-crm가 city의 다운그레이드를 승인한 뒤 작성자가 email의 다운그레이드를 푸시하면, 그 승인이 둘 다에 적용된다. 브랜치 보호에서 "dismiss stale pull request approvals when commits are pushed that affect the diff in the pull request"를 설정한다.
  • 한 사람의 승인이 팀 전체를 대변한다. 코드 소유자 한 명의 승인만으로도 GitHub의 요구 조건이 충족되며, 브랜치 보호의 승인 수는 브랜치 단위로 계산된다. 한 도메인이 더 많은 승인을 원한다면 작업에서 팀별로 승인 수를 센다.
  • 막힌 팀이 게이트를 수정한다. 풀 리퀘스트가 실패한 팀이 ci.toml에서 검사를 제거하거나, 면제를 추가하거나, CODEOWNERS를 수정한다. 이 세 가지 모두에 플랫폼 팀을 코드 소유자로 지정한다.
  • 풀 리퀘스트 밖의 변경. 노트북이 테이블을 만들거나 마이그레이션이 수동으로 실행된다. 2장이 problems을 실행하듯이, 이 작업도 프로덕션을 대상으로 일정에 따라 실행한다.

이 장에서 결정한 것

마지막으로 변경된 판: 2026.11.27판
  • 하나의 작업이 모든 풀 리퀘스트에서 2장부터 7장까지의 검사를 실행한다. 이 작업은 lib.ci.run이고, 검사 목록은 governance/ci.toml에 있다. 3장의 값 샘플링만 대신 일정에 따라 실행된다. lib.ci.main은 종료 코드를 반환하고 보고서를 Markdown으로 작성한다.
  • 이 작업은 풀 리퀘스트가 바꾸는 내용을 판단한다. 풀 리퀘스트가 새로 만든 발견 사항은 승인이나 면제를 받지 않으면 작업을 실패시키고, 이미 main에 있는 발견 사항은 소유자와 함께 보고하되 아무것도 실패시키지 않는다. 비정상 종료한 검사는 실패한 발견 사항 하나로 센다.
  • 모든 발견 사항에는 안정적인 ID가 있다. ID는 검사와 그 대상으로 이루어지며, 예를 들면 coverage/crm.learners.work_email이다.
  • 풀 리퀘스트는 임시 플랫폼에서 main 브랜치와 비교한다. 임시 플랫폼은 실제 플랫폼이 동작하는 방식대로 만들며, 각각 자체 마이그레이션과 파이프라인을 가진다.
  • 스키마 변경은 필드 ID로 비교하고 세 가지로 보고한다. Iceberg 리더, SQL이 해당 열을 이름으로 가리키는 파이프라인, 그리고 계보가 도달한다고 밝히는 모든 열이며, 여기에는 INDIRECT 간선도 포함된다.
  • 우리가 직접 정한 규칙이 두 가지 있다. 분류 등급을 낮추거나, 소유자를 바꾸거나, 테이블을 다른 도메인으로 옮기려면 main 브랜치에 있는 해당 테이블 소유자의 승인이 필요하며, 승인은 팀별로 센다. 그리고 열은 main 브랜치가 deprecated로 표시한 뒤에만 제거한다.
  • 소유권은 테이블마다 하나의 ODCS 계약으로 표현한다. 계약에는 도메인 하나와, owner 역할을 맡은 소유 팀을 적는다. 계약은 도메인별 폴더로 생성되고 CODEOWNERS 줄이 함께 만들어지며, 작업이 이를 검사한다. 플랫폼 팀은 CODEOWNERS, 작업의 설정, 전역 규칙, 면제, 마이그레이션을 소유한다.
  • 전역 규칙과 도메인 규칙은 Rego로 작성하며, 접근 정책의 폴더 밖에 두고 모든 계약에 대해 regopy로 프로세스 내에서 실행한다.
  • 의도적으로 심어 둔 공백은 main에 그대로 남는다. marketing.audience와 ai.review_corpus는 설명이 작성될 때까지 플랫폼 팀을 소유자로 하는 커버리지 발견 사항으로 모든 보고서에 나타난다.
  • 노이즈는 검사별로 아무도 조치하지 않는 발견 사항, 즉 면제되었거나 main에 남은 발견 사항으로 측정한다. 발견 사항 대부분이 무시되는 검사는 검사가 틀렸거나 플랫폼이 틀린 것인데, 개수만으로는 어느 쪽인지 알 수 없다. 면제는 발견 사항 하나, 소유자, 사유, 최대 90일 이내의 종료일을 명시하며, 커버리지와 강제 적용 테스트는 면제하지 않는다.
  • 풀 리퀘스트 검사는 변경의 크기에 맞춰 실행하고, 값을 읽는 검사는 일정에 따라 실행한다. 검사는 사람들이 계속 켜 두는 동안에만 쓸모가 있으므로, 각 검사는 변경의 크기에 맞춘다.

이 판의 이 장

2026.11.31판예제 통과 2026년 11월 19이 장에서 10개 예제개 중 10개가 통과한다

영어판 2026.11.31판을 번역한 것이다.

이 절 인용

형식

각 형식은 이 번역이 따르는 영문 원서를 출처로 표기한다.

모든 형식은 이 판을 명시한다. 링크는 현재 판을 열며, 여기서 절의 제목은 본문이 마지막으로 바뀐 시점을 알려 준다. 접근 날짜와 검색 날짜는 이 자료를 여는 날짜다.

이 페이지의 내용

10장 중 10장: Governance in CI

  1. Run every check as one job
  2. 커밋이 아니라 풀 리퀘스트를 관문으로 삼는다
  3. Report what a schema change reaches
  4. 분류를 낮추기 전에 소유자에게 물어라
  5. Deprecate a column before removing it
  6. Route each domain's reviews by path
  7. Layer domain rules on the global rules
  8. 검사별로 면제된 발견 사항 세기
  9. 운영 환경에서 무엇이 잘못되는가
  10. A check that reads every row
  11. 모든 ID에 경고를 내는 검사
  12. 깨진 파일은 발견 사항이 된다
  13. 그 밖의 실패
  14. 이 장에서 결정한 것

맨 위로 돌아가기전체 장