What is Policy Versioning?
Policy versioning is the practice of tracking changes to policy documents over time using version control (git), enabling audit trails of who changed what and when, rollbacks to previous versions, and code review workflows for policy changes.
WHY IT MATTERS
A policy that was correct last week might not be correct today. New tools are added, agent scopes change, compliance requirements evolve, and incidents reveal gaps. Policies must change — but uncontrolled changes to security policies are themselves a security risk. A misconfigured policy could expose sensitive data or block legitimate operations. An unauthorised change could weaken controls without anyone noticing.
Policy versioning solves this by applying the same rigour to policy changes that software engineering applies to code changes. Every modification is a commit with an author, timestamp, and message explaining why the change was made. Every version is preserved, so you can see exactly what the policy looked like at any point in history. Differences between versions are visible as diffs, making review straightforward.
For compliance, policy versioning is essential. Auditors need to know not just what your current policies are, but what they were during the audit period. If a security incident occurred on a specific date, you need to know which version of the policy was active at that time. Git provides this history automatically — every commit is a snapshot that can be reconstructed.
Versioning also enables safe experimentation. Teams can branch, test policy changes against real traffic patterns, and merge only after validation — reducing the risk that a well-intentioned change creates a new vulnerability.
HOW POLICYLAYER USES THIS
In PolicyLayer, a policy is a single JSON document attached to a grant, edited in the dashboard's visual policy builder and validated against the schema on save. The Raw JSON view exposes the exact document, so teams that want git-based review export it to a repository — every change goes through a pull request, gets reviewed by a security or platform team member, and is pasted back into the Raw JSON view only after approval. Because the document attached to the grant is the version the gateway enforces, the dashboard always shows the active policy, and the git history serves as a complete audit trail of every change, who made it, and when.