Policy as code for coding agent permissions
What matters first
Section titled “What matters first”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.
Policy rule table
Section titled “Policy rule table”| Policy area | Example rule | Why it belongs in policy |
|---|---|---|
| Repository access | Agent may read only repos or paths attached to the approved task | Prevents cross-repo exploration by convenience |
| Write scope | Agent may edit docs, tests, or named paths only after task approval | Stops quiet scope expansion |
| Sensitive files | CI, infra, auth, billing, secrets, and dependency files require stronger approval | Protects high-blast-radius changes |
| Tool and command use | Network, package install, migration, deploy, and destructive commands require explicit permission | Prevents risky side effects hidden inside implementation |
| PR creation | Agent may open PRs only with summary, tests run, and limitations | Keeps review evidence consistent |
| Merge and deploy | Agent cannot merge or deploy unless a narrow pre-approved class exists | Separates authoring authority from release authority |
| Escalation | Ambiguous scope, missing tests, or policy conflict must stop and ask | Makes safe stopping behavior testable |
The visitor should leave with a policy surface, not only an abstract governance principle.
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.
Policy should not replace review
Section titled “Policy should not replace review”| Review question | Why policy alone is not enough |
|---|---|
| Is the design the right one? | Policy can block unsafe paths but cannot judge architecture quality fully |
| Is the change maintainable? | Maintainability needs domain ownership and code review |
| Is the test meaningful? | A policy can require tests, but reviewers must judge whether the test covers the risk |
| Is the user impact acceptable? | Product and support owners still need context |
| Should this ship now? | Release timing is an operational decision, not only a permission rule |
Policy creates the guardrails. Review still owns judgment inside those guardrails.
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.