Git-Native Agent Definitions as the Enforcement Boundary for Governance Policy

Agents-as-code means defining AI agents in YAML files stored in Git, so their permissions and the rules they run under go through the same version control, pull request review, and CI validation as application code. Git-native agent definitions make the repository an enforcement boundary when those checks can block unapproved policy changes and the execution environment enforces the approved definition. Production governance depends on that chain of controls.

Why "just run it in the cloud" is not a governance model for coding agents

A runaway loop can use up a budget overnight, while a force-push can rewrite commit history. Both failures can still happen when the agent moves from a developer’s laptop to a cloud VM. Hosting changes where the agent runs while leaving its permissions unchanged. The missing control is an enforcement surface outside the agent, able to stop an operation even when the model decides to attempt it.

The Microsoft Agent Governance Toolkit README states that “Prompt-level safety ('please follow the rules') is not a control surface. It is a polite request to a stochastic system.” Instructions in CLAUDE.md, system prompts, and natural-language rules work only if the agent remembers and follows them through adversarial input or long, multi-step runs. That is not a dependable authorization mechanism. The obstacle between a capable pilot and a production deployment is therefore not simply model performance, but the isolation, governance, compliance controls, and auditability that security teams require.

What it means for a git repository to be an enforcement boundary

An enforcement boundary is a point where policy is checked and an action can be structurally blocked before it happens. Logging a violation afterward does not meet that definition. Neither does raising a flag that lets execution go on. For agent governance, the repository becomes such a boundary when access controls, required reviews, branch protection, and CI gates control which definitions may take effect.

This is more than storing configuration in Git. A YAML file in an unprotected branch states what should happen, but on its own it cannot stop a policy change that has not been approved. Required status checks and CODEOWNERS approval requirements control how that file becomes part of the approved configuration.

Terraform configurations provide a useful analogy for this separation. They let teams keep infrastructure definitions under version control and review them, and agent YAML definitions do the same for how agents behave. A git diff exposes a changed permission, and git blame attributes the relevant edit. Required review then puts a decision between that edit and its adoption, rather than leaving governance to reconstruction after an incident.

How do you define AI agents in YAML before a session begins?

A declarative manifest separates the agent’s intended task from its permitted capabilities. The task describes what it should accomplish. The permission definition establishes which actions remain available while it pursues that task, making least privilege reviewable before the first tool call. Enforcement still occurs when an action is attempted, but the authority for that decision has already been defined.

The toolkit implements this distinction in policy.yaml. Its default_action field sets the default posture, while named rules match on action.type and apply deny or require_approval effects. Its safe_tool evaluates that YAML policy deterministically on every call.

OpenGAP extends the pattern through agent.yaml and DUTIES.md, with explicit permissions for maker, checker, executor, and auditor roles. Its conflict matrix prohibits designated role combinations, while handoff rules require multi-role sign-off for specified actions. The CLI validates those constraints before deployment.

Budget limits and credential references belong in the same permission-scoping model. A hard budget cap must intercept execution before the next API call and terminate the session when the limit is reached. The manifest should hold references to credentials rather than their literal values, so secrets stay out of version control and the access the agent needs is still clear.

How primitive blocking closes the gap between written rules and enforced behavior

Operations that bypass a reviewed definition’s controls pose the strongest objection to YAML-based governance. If an agent can invoke a raw primitive outside the policy evaluator, the file describes only one available path. Primitive blocking closes that gap by removing the raw operation and exposing a governed replacement as the available tool.

The replacement can also improve the operation itself. dev_commit validates that staged changes exist, requires a commit message, and adds a co-author trailer for AI/human attribution. dev_reset defaults to a mixed reset and requires an explicit confirm_hard=true parameter for a hard reset.

Blocking a direct command alone is not sufficient. After a primary block fires, agents can try to run an operation indirectly through variable expansion, piped commands, or shell escapes. Defense in depth must cover those evasion paths so that each leads back to the governed tool. Better tools reduce the incentive to circumvent controls, but unavailable bypass paths provide the actual enforcement.

This is the control missing from the opening force-push scenario. A governed path that prohibits the operation, with raw and indirect paths blocked, would prevent the history rewrite. A reminder in a prompt would only discourage it.

Why the PR review step is not optional ceremony — it is the human-in-the-loop gate

Changing an agent’s tool allowlist or budget cap changes its authority. Even a diff of only a few lines therefore calls for a decision on how the agent is governed. Once definitions are in protected repository paths, the PR controls already in place can govern those changes without a separate review system just for agents. The human-in-the-loop gate precedes the agent’s use of the new authority.

The agent-repo-governance resolution sets out this control in its probe-gate ruleset. A merge to the default branch requires a PR, at least one approval, and a passing required status check, with no bypass actors. The platform enforces that prerequisite independently of the model. Human reviewers accept or reject a proposed change, while the gate deterministically prevents an unapproved change from merging.

The resulting record also supports audit work. Each merged PR records which definition changed, who approved it, and when. Git log and git blame supply the corresponding change history and attribution.

How CI pipelines extend the enforcement boundary from merge-time to every push

Commit-time validation catches malformed YAML and missing required fields before a push. Failure appears at the developer’s terminal without a remote round-trip. That early feedback is useful, but a local hook cannot be the only gate because an automated PR or another execution context may omit it. PR-time validation therefore repeats the checks as a required status check and tests semantic policy constraints before merge.

The toolkit uses a ci-complete job as a branch-protection gate that depends on the other CI jobs. Making that completion job required prevents a PR from merging unless all applicable checks pass. This is distinct from standards coverage. The Agent Compliance package provides coverage across OWASP Agentic AI Top 10, NIST AI RMF 1.0, EU AI Act, and SOC 2, rather than the completion job providing that mapping.

The definition that runs must match the approved artifact. A Deterministic Control Plane for LLM Coding Agents proposes Rel(AI)Build, a reference implementation that treats agent definitions as a managed supply chain using SHA-256 content addressing, cryptographically authenticated lockfiles, and hash-chained audit logs. These mechanisms address silent modification and undeclared propagation between merge and runtime, with hash chaining providing tamper evidence for the execution record.

GitAgent extends repository-backed state into execution through its “stateless compute, git as state” pattern. Agents run in ephemeral compute and commit meaningful events to dated, job-ID-scoped branches named runtime//. Git history then supports deterministic replay and failure recovery. This adds execution evidence to the reviewed definition rather than treating a successful merge as the end of governance.

What segregation of duties looks like when it is a file, not a process

OpenGAP’s segregation-of-duties pattern turns role separation into a testable configuration constraint. Its agent.yaml declares role permissions and a conflict matrix that can prohibit one agent from holding both maker and checker roles. The prohibition is explicit and machine-checkable before deployment. It does not depend on an operator noticing that one agent has accumulated incompatible responsibilities.

Handoff rules cover actions that need more than one role to take part. Setting approval_required to true on a handoff entry, with enforcement set to strict on the segregation_of_duties block, makes approval a declared prerequisite. The gitagent validate or opengap validate command catches SOD violations before deployment. When CI requires validation, an assignment with a role conflict can enter the approved definition only after a policy change has been reviewed.

DUTIES.md makes those responsibilities readable to a compliance officer without a dashboard query or vendor access. The YAML supplies the machine-checkable control, while the Markdown file states the roles and conflicts for human review. Auditors can inspect the policy artifact and its validation history, then follow the PR number, approver, and timestamp associated with a change.

This establishes a concrete SOD control. Its scope is the declared role conflicts and handoff requirements that validation and execution enforce.

Where session isolation fits into the governance model the repo defines

Repository controls establish which definition is authorized, but the execution environment must enforce it. Sandbox parameters, credential references, and network policy have no effect if the session can ignore them. Each session therefore needs freshly minted credentials that are revoked on completion.

The “brain outside, hands inside” pattern separates model access from tool execution. The model client, which holds the API key and communicates with the model, runs outside the sandbox. Shell operations, file edits, the test runner, and the package manager run inside a locked-down container that has no persistent credentials and limits network access. Only trusted destinations can be reached over the Internet, and CI/CD workflows need human approval before they run.

The runtime record must connect this execution to its authority. Each session should record a run ID, the human initiator, the agent identity and model version, and the task description. It should also record every tool call with its arguments and exit code, every file written with its path and hash, and network activity against the list of allowed destinations. Those details make actions attributable to a definition version and a specific trigger, person, or automated process.

Without that record, review proves only what was approved. Session evidence allows the approved configuration to be compared with what actually ran.

From pilot to production — what the enforcement boundary makes possible that runtime hope does not

Production readiness requires an answer before execution to who granted an agent authority, what limits apply, and which mechanisms will enforce them. A successful pilot does not supply those answers. Versioned definitions, protected review paths, required validation, and isolated execution provide a way to establish them without relying on model compliance. Runtime controls remain necessary, but their policy comes from an attributable, approved artifact.

Treat agent definitions as code from day one. Teams should check YAML manifests into the repository, apply branch protection and CODEOWNERS to their directories, and require CI validation that fails on schema or SOD violations. They should also block raw primitives in favor of governed alternatives. Each session should run in an isolated environment with session-scoped credentials and a hard budget cap set in the manifest and enforced before the next call.

This model does not eliminate operational risk. The decisive boundary is not the location of the YAML file alone, but the connected controls that prevent unapproved definitions from taking effect and prevent execution from exceeding approved permissions.