Policy-as-code

Policy-as-code means expressing compliance rules as executable code that runs automatically in the CI/CD pipeline, rather than as documents that developers are expected to read and follow manually. Instead of a policy document that says "all AI-generated code must have a human reviewer," a policy-as-code implementation is a CI check that fails if the PR lacks a human approval record from a non-author account. The policy is enforced, not hoped for.

The technical foundation for policy-as-code in most organizations is Open Policy Agent (OPA), a general-purpose policy engine that evaluates structured inputs (JSON representing commit metadata, PR attributes, security scan results) against Rego policy rules and returns a decision: allow or deny. OPA integrates with CI systems (GitHub Actions, GitLab CI, Jenkins), Kubernetes admission controllers, API gateways, and infrastructure provisioning tools. A single OPA policy can enforce the same rule across all of these integration points simultaneously.

At L3 (Systematic), policy-as-code applies to the delivery pipeline specifically: CI checks that enforce AI disclosure requirements, block merges that lack required audit trail fields, verify that AI-generated code in high-risk repositories was reviewed by a human with specific permissions, and confirm that model versions used are on the approved list. The policy lives in the repository alongside the code it governs, goes through code review when it changes, and its enforcement decisions are logged and auditable.

The shift from document-based policy to policy-as-code has a profound effect on compliance reliability. Document-based policies have adoption rates that peak at launch and decay over time - developers skip steps under deadline pressure, new developers don't find the policy document, policy updates don't reach developers who were already past onboarding. Policy-as-code has adoption rates that are mechanically enforced: every merge request, every deployment, every time. The compliance evidence is the CI run log, not a survey about whether people read the policy.

• Compliance is mechanically enforced, not behaviorally dependent - policy-as-code eliminates the failure mode where developers know the policy but don't follow it under pressure; the pipeline either passes or fails, regardless of deadline urgency
• Policy changes go through code review - when a compliance rule changes, the change to the policy code goes through the same review process as application code, creating an auditable history of what was required when
• Audit evidence is the CI log - instead of collecting attestations from developers or doing periodic audits, the compliance evidence is the automated check results that run on every merge; this is a much stronger evidence base for SOC2 and ISO 27001
• Scales automatically with team growth - adding a new team or repository to the policy scope requires adding it to the OPA policy config, not training new developers on a document they may not find
• Enables proactive policy testing - policy rules can be unit-tested like application code; you can verify that a rule correctly rejects a non-compliant commit before it ever runs in production CI
• Covers agent config files, now a live attack surface - in May 2026 agent configuration became something attackers write to, so policy-as-code must lint, normalize, and review these files like code; the Mini Shai-Hulud worm (CVE-2026-45321, CVSS 9.6) planted persistence by writing Claude Code hooks into ~/.claude/settings.json, and the TrapDoor campaign hid zero-width-Unicode prompt injection inside CLAUDE.md and .cursorrules across 34 poisoned packages
• Encodes vendor sovereignty as a hard control - June 2026 made model availability a governance risk, not just a procurement detail. Anthropic disabled Fable 5 and Mythos 5 worldwide on June 12 to comply with a US export-control order, and Fable 5 on Bedrock was found to route inference data back to Anthropic, breaking Bedrock's data-residency guarantee. Policy-as-code should now enforce model and vendor portability (no pipeline pinned to a single un-substitutable model), data-residency routing (inference confined to approved Bedrock/Vertex/Foundry EU regions), and a self-hostable fallback so a model that disappears overnight does not halt delivery

1. Install OPA and write your first policy - start with the simplest possible policy: a CI check that reads the commit message and verifies it contains an AI-Model: trailer if the PR author has the "AI-user" team label. Write the Rego rule, test it against sample inputs (compliant commit, non-compliant commit), and add it as a GitHub Actions step. The first policy takes a day to build; every subsequent policy takes an afternoon.
2. Create a policy repository - store your OPA policies in a dedicated repository (or a policy/ directory in your platform monorepo) with a test suite and a CI pipeline that validates policies before deployment. This creates the same code quality guarantees for policy code that you apply to application code.
3. Start with non-blocking advisory mode - before making policies blocking, run them in advisory mode for two weeks: the CI check runs, logs its result, but doesn't fail the build. Use this period to see how many PRs would fail, fix any false positives in the policy logic, and communicate the change to developers before it takes effect.
4. Define the policy input schema - OPA policies evaluate structured JSON input. Define the input schema for your CI context: what fields are available (commit author, PR reviewers, commit message content, changed files, labels, security scan results, AI disclosure fields). This schema is the contract between your CI system and your policies.
5. Build the policy test suite - for each policy rule, write test cases: a compliant example that should pass, multiple non-compliant examples that should fail, and any edge cases (first PR from a new developer, emergency bypass process). The test suite runs in CI and prevents policy regressions.
6. Document the exception process in the policy code - every policy should have a documented exception path: an emergency bypass label (compliance/exception-approved) that allows a merge to proceed with override, requiring a follow-up ticket within 48 hours. The exception is captured in the CI log; the follow-up is tracked in the issue tracker. No dark paths around policy.

Writing policies that are too strict too fast. A policy that fails half of existing PRs on day one will be overridden, complained about, and disabled. Start with policies that reflect current best practice (not aspirational practice) and tighten them over time as teams improve. The first policy should have a 95% pass rate on existing PRs; only then start using it to drive behavioral change.

Not providing actionable failure messages. When an OPA check fails, the developer should know exactly what to do to fix it. "Policy violation: missing AI audit fields" is not actionable. "This commit appears to be AI-assisted but is missing required audit fields. Add AI-Model: <model-id>, AI-Timestamp: <ISO timestamp>, AI-Context: <description>, AI-Approver: <email> to your commit message. See docs/ai-audit-trail.md for details." is actionable.

Treating policy code as exempt from review. Policy changes have compliance implications - a policy that accidentally allows a prohibited pattern or blocks a legitimate use case has real consequences. Policy code should go through the same review process as security-sensitive application code, with at minimum two reviewers including someone from security or compliance.

No exception process. A policy with no exception process will either be routinely overridden (if developers can bypass it) or will create genuine blockers (if they can't). The exception process must be documented, fast (same-day or next-day approval), and auditable. The exception itself is compliance evidence - an organization that has a well-used, well-documented exception process is demonstrating mature governance.

Forgetting that policies need updating. When AI tools evolve (new model versions, new agent capabilities, new use cases), policies that were written for an earlier state of AI tooling will generate false positives and false negatives. Build a quarterly policy review into your governance calendar, triggered by either the calendar date or by a significant change in the AI tool stack.