Outcome
By the end of this lesson, you will be able to wire the CI check via the onboarding flow, read an inventory scan’s managed-versus-orphan split, and use a governed override without losing the audit trail.
| Tier | Engineer |
| JTBD | ”Get this running across our repositories without a week of CI plumbing.” |
| Personas | Platform Engineer · SRE |
| Prerequisites | M5.8.L3 |
| Time | 9 minutes |
| Bloom verb | Wire (Apply), Read (Apply), Use (Apply) |
1. Concept
Governance that depends on every team remembering to add a file never finishes rolling out. This lesson is the part that removes the remembering.
CI onboarding opens the pull request for you
THE ONBOARDING ENDPOINT DOES TWO THINGS:
1. MINTS A SCOPED SCAN TOKEN 2. OPENS A PULL REQUEST adding a Terraform- and OpenTofu-aware GitHub Action to the repositoryThat second step matters more than it sounds. The alternative is a documentation page asking each team to add a workflow file, and that is where these rollouts die. Fourteen repositories means fourteen teams doing a small annoying task at their own pace. It never finishes.
Opening the PR turns adoption into a review rather than a task. Teams still consent, and they consent by merging something rather than by building something.
The token is scoped to the scan, so a leaked CI token is not a ZopNight credential in any broader sense.
The two things the CI does
ON A PULL REQUEST runs the plan gate (L1, L3)ON A SCHEDULE/BRANCH runs the inventory scanReading the inventory scan
The scan links declared resources to discovered inventory:
MANAGED declared in IaC AND present in the cloudORPHAN present in the cloud, NOT declaredWHY THE ORPHAN LIST IS THE VALUABLE OUTPUT
An orphan is not governed by anything you have. It will not be caught by your PR gate, because it never appears in a plan. It drifts freely, it is disproportionately likely to be untagged, and the next `apply` will not reconcile it.
Everything else in this track assumes your resources are managed. The orphan list tells you which ones the assumptions do not apply to.Three useful ways to work the list:
1. BY COST. The expensive orphans are where the money and the risk concentrate.
2. BY AGE. An orphan created last week is somebody's work in progress. One from 2023 is abandoned.
3. AGAINST YOUR TAG COVERAGE GAP (T3.M3.5.L4). These two lists overlap heavily, and each explains the other: untagged resources are usually orphans, and orphans are usually untagged.Governed override
AN OVERRIDE IS AVAILABLE, AND IT IS AUDITED.Both halves are the design.
WHY AN OVERRIDE EXISTS AT ALL A policy engine with no escape hatch does not produce compliance. It produces avoidance: the change moves outside IaC, into the console, where you have no gate at all and no record.
An override you can see is strictly better than a console change you cannot.
WHY IT IS AUDITED An override that leaves no record is indistinguishable from the policy not existing.The right way to read your override log is as a policy quality signal:
ZERO OVERRIDES either your policies are perfectly calibrated, or people are routing around the gate entirely. Check which.
A FEW, VARIED healthy. Genuine exceptions exist.
MANY, ON ONE POLICY that policy is miscalibrated. The fix is the policy, not more overrides.That third pattern is the one to watch for at your quarterly review. A policy overridden fifteen times has been voted on, and the vote was against it.
The governance dashboard
POLICIES what is defined and what is blockingVALIDATIONS the run history and their decisionsREPOSITORIES what is wired and what is notThe repositories view is the rollout tracker: it tells you which repos have merged the onboarding PR and which have not, which is the question that actually determines whether your coverage claim is true.
Agent-reachable
Policy CRUD, CI wiring and token management, validation-run reads and the catalogs are all MCP tools. On a default-tier org that means an agent can answer “which repositories are not wired” and “what did the last validation on this repo decide” without opening the dashboard, and cannot change any of it.
2. Demo
A rollout across 14 repositories:
WEEK 1: ONBOARDING Ran the onboarding flow against all 14. It minted scoped tokens and opened 14 pull requests.
Merged in week 1: 9 Merged in week 2: 3 Still open at week 4: 2 one repo archived but not marked as such one team wanted a security review of the Action first, which was reasonable
CONTRAST WITH THEIR PREVIOUS ROLLOUT A documentation page asking teams to add a workflow. After two months: 4 of 14. The difference is that a PR is a review, and a doc page is a task.
WEEK 2: FIRST INVENTORY SCAN Across the 12 wired repos:
managed 1,847 resources orphan 1,190 resources (39%)
ORPHANS BY COST, top 3 an entire staging environment $4,200/mo built during an incident in 2024, never codified a legacy RDS pair $1,900/mo predates their IaC adoption 47 assorted EBS volumes $310/mo
ORPHANS BY AGE under 30 days 88 work in progress, fine 30-365 days 402 over a year 700 the real backlog
CROSS-REFERENCED WITH TAG COVERAGE Their untagged-resource list and their orphan list overlapped by 71%. Each explained the other, and it turned two separate remediation projects into one.
MONTH 2: THE OVERRIDE REVIEW 18 overrides in the first month.
14 of the 18 were on ONE policy: a reliability rule requiring multi-AZ on all managed databases. It was firing on staging databases, where single-AZ is correct.
FIX: scoped the policy to production. Overrides on it dropped to zero.
4 were genuine one-off exceptions, varied, each with a reason recorded.
THE READING 14 overrides on one policy is not 14 exceptions. It is one miscalibrated policy that had been voted on. The override log found it in a month; without it, that policy would have quietly trained everyone to click through.3. Hands-on (6 min)
1. Open the governance dashboard, Repositories view. wired: ______ not wired: ______ Is your coverage claim true? Y / N
2. Run an inventory scan on one repository. managed ______ orphan ______ orphan % ______
3. Sort orphans by cost. Top orphan: ______________________ $______/mo Do you know why it exists? Y / N
4. Cross-reference your orphan list against your untagged-resource list. Overlap: ______% (High overlap means one project, not two.)
5. Review your override log: total overrides ______ most-overridden policy ______________________ count on it ______ If that count is high, fix the policy.4. Knowledge check
Q1
Why does CI onboarding open a pull request rather than documenting the workflow file for teams to add?
A. Because a documentation page turns adoption into a small annoying task done at each team’s own pace, which is where governance rollouts stall
B. Because the workflow file changes frequently and any documented version of it would go stale in the docs almost immediately
C. Because the scan token has to be committed into the repository itself, which only a pull request can do safely for you
D. Because GitHub requires that the Action be added by the very same app that later reads it back out again at scan time
Show answer
Correct: A. Opening a PR makes adoption a review instead: teams still consent, by merging something rather than by building it. C is specifically wrong: the token is scoped to the scan and minted by the onboarding flow, not committed. The rollout-rate difference between a PR and a doc page is usually large and is the point.
Q2
An override log shows 18 overrides in a month, 14 of them on a single policy. The correct reading:
A. The team is routing around governance and needs training
B. Fourteen legitimate exceptions, since each was recorded
C. One miscalibrated policy, not fourteen exceptions
D. Overrides should be disabled for that policy
Show answer
Correct: C. The policy has been voted on and the vote was against it. The fix is to scope or adjust that policy; without the log, it would have quietly trained everyone to click through. In the worked example the policy required multi-AZ on all managed databases and was firing on staging, where single-AZ is correct. Scoping it to production dropped overrides on it to zero.
Q3
Why does a governed override exist at all, rather than policies being absolute?
A. To let administrators bypass the checks entirely during an incident, when there is no time to wait for a policy change to be reviewed and merged first
B. Because some policies simply cannot be evaluated on every plan, so an override is the only way to let those particular plans through the gate successfully
C. To support the gradual rollout of new policies, so a rule can be introduced in warn mode and then tightened once the noise has been measured properly
D. Because a policy engine with no escape hatch produces avoidance rather than compliance: the change moves outside IaC into the console, where there is no gate and no record
Show answer
Correct: D. An override you can see is strictly better than a console change you cannot. The auditing is the other half: an override leaving no record would be indistinguishable from the policy not existing, and it is the record that turns the override log into a policy-quality signal.
5. Apply
Use the onboarding flow rather than documenting the workflow, and track adoption in the Repositories view rather than assuming it. The gap between “we rolled this out” and “twelve of fourteen repositories merged it” is the gap between a claim and a fact.
Review your override log quarterly and look for concentration on a single policy. That pattern is a miscalibrated policy telling you so, and it is cheaper to fix than to keep overriding.
Related lessons
- L3: Cost guardrails in the pull request
- L1: Decision, not enforcement
- T3.M3.5.L4: Tag coverage widget
- T5.M5.6.L2: IaC drift detection
Glossary terms touched
Scoped scan token · Inventory scan · Governed override · Orphan resource