deliveryL3 SystematicGovernance & Compliance

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.

·Minimum viable audit trail is captured per AI-assisted change: model identifier, timestamp, context description, human approver
·Policy-as-code enforces compliance rules in CI (OPA or equivalent)
·Compliance gates run on every PR to in-scope repositories

·Audit trail fields are validated by CI (missing fields fail the build)
·Policy exceptions are logged and require follow-up within 48 hours

Evidence

·Sample commit or PR metadata showing model, timestamp, context, approver fields
·OPA policy configuration in CI pipeline
·Compliance gate pass/fail logs

What It Is

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.

Why It Matters

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

Getting Started

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.
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.
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.
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.
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.
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.

Tip

Start with OPA Playground (play.openpolicyagent.org) to write and test Rego policies before deploying them. The playground lets you paste a policy and input JSON, run the policy, and see the decision. It's much faster than deploying to CI for iteration.

6 steps to get from here to the next level

Common Pitfalls

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.

Mistakes teams actually make at this stage - and how to avoid them

How Different Roles See It

BobHead of Engineering

Bob has been managing AI governance through policy documents and PR template fields for six months. The compliance rate on PR disclosures is 75% - good, but not auditable at the level his SOC2 auditors expect. They want evidence that the policy is enforced, not just documented. Bob needs to close the gap between "we have a policy" and "we enforce our policy."

What Bob should do: Bob should scope a one-sprint policy-as-code implementation for the highest-priority compliance requirement: AI disclosure in PRs to SOC2-scope repositories. The implementation steps are: (1) an OPA policy that checks for required AI disclosure fields in PR descriptions, (2) a GitHub Actions integration that runs the check on every PR targeting main, (3) two weeks of advisory mode with 100% of failures logged and reported, (4) one week of remediation (fixing the 25% non-compliant PRs, adjusting the policy logic if needed), (5) enforcement mode. This moves the compliance rate from 75% behavioral compliance to 100% enforced compliance for the in-scope repositories, and gives Bob concrete CI run logs as audit evidence.

What Bob should do - role-specific action plan

SarahProductivity Lead

Sarah has been manually reviewing PR disclosure data every month to check compliance rates. The process takes two hours per review cycle and the data is often incomplete because some PRs lack disclosures and she has to chase down the developers who submitted them.

What Sarah should do: Sarah should champion the policy-as-code implementation as a productivity tool for her own work. Once policy enforcement runs automatically in CI, the compliance data is collected automatically in the CI run log - no manual review needed. Sarah should work with the platform team to build a simple analytics pipeline that reads the CI policy check results, computes weekly compliance rates by team and repository, and populates her productivity dashboard automatically. The policy-as-code implementation eliminates her manual compliance review work and improves data quality simultaneously. Sarah should frame this as: "policy-as-code gives me better compliance data with less work - it's a win for governance and a win for developer experience."

What Sarah should do - role-specific action plan

VictorStaff Engineer - AI Champion

Victor has been informally advocating for policy-as-code for months and has already written prototype OPA rules for the AI audit trail requirements. He wants to get the organization to adopt them but has been waiting for the right moment.

What Victor should do: Victor should present his prototypes with concrete data from a dry run. He should run his OPA policies against the last 90 days of commit history in the most important repository and produce a report: X% of AI-assisted commits would have passed, Y% would have failed, and here is the breakdown of failure reasons. This moves the conversation from "should we do policy-as-code?" to "here's what policy-as-code would have caught." Victor should also address the rollout path explicitly: advisory mode for 30 days, then enforcement with an exception process that he's already designed. Having a complete proposal with working code, dry-run data, and a rollout plan is far more likely to get approval than an abstract recommendation.

What Victor should do - role-specific action plan