Policy as code for coding agent permissions
Quick answer
Section titled “Quick answer”Coding-agent governance gets stronger when permissions are expressed as policy, not as reviewer mood.
If your team cannot clearly state which agent may:
- read a repository,
- write code,
- change tests,
- touch CI,
- open a pull request,
- merge,
- or deploy,
then your approval model does not scale.
Why policy as code matters here
Section titled “Why policy as code matters here”Human review is still necessary for risky changes, but review alone is not a permissions system.
When teams rely only on reviewer judgment, they create:
- inconsistent boundaries across repositories,
- unclear expectations for agents and developers,
- weak auditability,
- and approval drift over time.
Policy as code fixes this by turning the boundary into something testable and repeatable.
The permission layers that should be explicit
Section titled “The permission layers that should be explicit”Most coding-agent programs should define policy for at least these layers:
- Repository read Which repositories or paths can the agent inspect?
- Bounded write Which files, folders, or change scopes can it modify?
- Workflow-sensitive files Can it touch CI, infrastructure, dependency manifests, or security-critical paths?
- Branch and PR actions Can it create branches, open pull requests, or update existing PRs?
- Merge and deploy Can it trigger merge, rollout, or production actions?
If these layers are not separately controlled, your permissions are too coarse.
What policy should encode
Section titled “What policy should encode”Healthy policy typically encodes:
- allowed repositories or path prefixes,
- forbidden file classes,
- environment access restrictions,
- human approval requirements by action,
- required checks before merge,
- and conditions that force refusal or escalation.
That gives teams a durable contract they can explain and review.
The practical rule
Section titled “The practical rule”Policy should block categories of risk, not only named commands.
For example, “no direct changes to deployment manifests” is better than “do not run tool X,” because the same risk may appear through different tools or workflows.
What not to encode
Section titled “What not to encode”Do not try to put every engineering decision into policy.
Policy should define boundaries, not replace code review. Its job is to answer:
- what the agent may do automatically,
- what it may propose but not finalize,
- and what it must never do without explicit human action.
That is enough to create real leverage without pretending policy can solve architecture quality.
A simple permission ladder
Section titled “A simple permission ladder”One healthy starting model:
Level 1: Read and analyze
Section titled “Level 1: Read and analyze”Allowed:
- repo read,
- search,
- test discovery,
- issue summarization,
- risk analysis.
Level 2: Bounded draft changes
Section titled “Level 2: Bounded draft changes”Allowed:
- edits in approved paths,
- test updates in local scope,
- documentation changes,
- branch creation,
- pull request draft creation.
Level 3: Sensitive workflow influence
Section titled “Level 3: Sensitive workflow influence”Requires stronger approval:
- dependency changes,
- CI changes,
- configuration edits,
- cross-service refactors.
Level 4: Merge or deploy impact
Section titled “Level 4: Merge or deploy impact”Human-controlled by default:
- merge,
- release,
- environment mutation,
- secret-sensitive operations.
Implementation checklist
Section titled “Implementation checklist”Your coding-agent permission policy is probably healthy when:
- read, write, branch, merge, and deploy are separate controls;
- forbidden paths are defined explicitly;
- risky file classes trigger stronger approval automatically;
- and reviewers can explain the policy without relying on institutional memory.