Treating policy documents like code isn’t just a clever idea — it solves real problems that SharePoint, Confluence, and annual review cycles never will.
The policy management problem nobody talks about
Every organisation with a compliance program has a policy library. Access control policy, incident response policy, acceptable use policy, change management policy — the list grows with each framework you adopt. These documents are usually born during an audit preparation sprint, reviewed by a committee that argues about wording for two hours, approved by someone with a title, and then uploaded to a SharePoint library or a Confluence space where they quietly fossilise — three clicks from the surface, last modified eighteen months ago, owner listed as someone who left the company.
A year later, the auditor asks for evidence of annual review. Someone opens the document, updates the “last reviewed” date in the footer, gets a signature, and uploads a new version. The document is functionally identical to last year’s. Nobody can tell you what changed, who proposed the change, who objected, or why the current wording is what it is. The approval is documented. The reasoning is gone.
This is the policy management status quo, and it’s a solved problem — just not in the security world yet.
Git is already an approval workflow
Software engineers figured this out a long time ago. When a change to a codebase is proposed, it goes through a pull request: a formal, documented proposal that captures what changed, why, and who reviewed it. Reviewers leave comments. The author responds. Someone with authority approves the merge. The entire conversation is preserved permanently, attached to the exact diff it produced.
This is also a perfect policy approval workflow. Consider the mapping:
| Policy process | Git equivalent |
|---|---|
| Draft a change | branch + commit |
| Circulate for comment | Open a pull request |
| Subject matter review | PR comments and requested changes |
| Legal / compliance review | Required reviewer approval |
| Final approval | merge by authorised owner |
| Effective date | Merge timestamp |
| Version history | git log |
| What changed between versions | git diff |
| Who approved and when | merge commit with author and timestamp |
Nothing here requires new tooling beyond what most engineering teams already use. GitHub, GitLab, Gitea — any platform with pull request support gives you the full workflow out of the box.
The audit trail writes itself
This is the part that should get compliance officers out of their chairs.
Auditors routinely ask for evidence that policies are reviewed, approved by appropriate personnel, and updated when material changes occur. Satisfying this requirement with a Word document means maintaining a version history table, collecting signatures, and keeping records of review meetings — all manually, all prone to being incomplete or inconsistent.
With a Git-based policy library, the audit trail is a byproduct of the workflow itself. Every change has an author, a timestamp, a commit message explaining the rationale, and a record of every reviewer who approved it before it merged. git log --follow policy/access-control.md gives you the complete history of that document from inception. git diff v2.1..v2.2 -- policy/access-control.md shows exactly what changed between review cycles, line by line.
You don’t compile this evidence for auditors. You export it. The difference in effort is not marginal.
Policy drift, and how version control eliminates it
Policy drift is what happens when documented procedures and actual practice diverge — usually quietly, over time, without anyone making a deliberate decision to let it happen. A procedure gets updated informally, the policy document doesn’t follow, and by the next audit the organisation is technically non-compliant with its own written policies.
In a Git-based workflow, changing how something is done creates natural pressure to update the policy that describes it. If a developer opens a PR to change a deployment procedure and the corresponding policy isn’t updated, reviewers can catch it. Linking policy documents to the systems and procedures they describe — and reviewing them together when either changes — is a practice that’s simply not possible when policies live in SharePoint and procedures live in Confluence and nobody is looking at both simultaneously.
Writing policies in Markdown
The practical objection is usually formatting. Policy documents need headers, tables, numbered lists, cross-references. Markdown handles all of this, renders cleanly in every Git platform’s web interface, and can be converted to PDF or Word for stakeholders who need it in those formats.
More importantly, Markdown is diffable in a way that Word documents are not. A change to a .docx file shows up in Git as a binary blob — you can see that something changed, but not what. A change to a .md file shows the exact lines added, removed, and modified. This is what makes the audit trail actually useful rather than just technically present.
The transition from Word to Markdown is a one-time cost. The operational benefits compound indefinitely.
Connecting back to OSCAL
If you’re implementing OSCAL — and you should be — Git-based policy management isn’t just compatible with that investment, it’s the natural extension of it. OSCAL system security plans reference policies. Those policies, if they’re in the same Git repository as your OSCAL artifacts, can be linked directly. A change to a policy triggers validation of any OSCAL documents that reference it. The compliance program becomes a coherent, version-controlled system rather than a collection of documents maintained in isolation.
This is what “compliance as code” means at the operational level: not just controls expressed in machine-readable formats, but the entire governance apparatus — policies, procedures, approvals, evidence — managed with the same rigour and tooling applied to the systems it governs.
The technology is not new. The application is.