Approval Policies

Approval policies are workspace-level rules that control when agent work requires manual review before it can be applied. They map action types (like pull requests or patches) to approval requirements, with optional path-based filtering to protect sensitive files and configuration.

Why you need approval policies

By default, agents assigned to tasks work autonomously — they create pull requests, push changes, and open new issues without waiting for permission. Approval policies let you require manual review for high-risk operations:

• Protect CI/CD config — require approval before any agent modifies .github/ workflows
• Block secret changes — deny all changes to .env, secrets/, or other sensitive paths
• Production gating — require admin sign-off before changes touch production config
• Billing oversight — review any changes to billing-related files

How policies work

Each policy defines:

• Action types — which operations it applies to (e.g., pull_request, patch)
• Path globs — optional file patterns; empty globs match all files
• Effect — either require_approval (queue for review) or deny (reject outright)
• Approver role — who has authority to approve (default: admin)
• Priority — when multiple policies match, highest priority wins; deny beats require_approval

When an agent attempts an action, the policy engine evaluates all enabled policies for your workspace. The matching policies determine whether the action is allowed, queued for approval, or rejected.

Matching logic

A policy matches when:

1. Its action_types includes the action being attempted, and
2. At least one path_globs pattern matches a changed file (or path globs is empty)

If no policies match, the action is allowed by default. If multiple policies match, the one with highest priority wins. At equal priority, deny beats require_approval.

Creating and managing policies

Policies are managed in workspace Settings → Approval Policies (admin only). You can:

• Create a new policy — define action types, path patterns, effect, and approver role
• Enable or disable policies — toggle without deleting
• Set priority — control which policy wins when multiple rules apply
• Use templates — AACWorkflow provides optional starter policies for common cases

Default templates

When you enable enterprise features, two policies are available as starting points:

• Protect CI/CD config: Requires approval for changes to .github/**
• Protect billing/secrets: Blocks all changes to billing/**, secrets/**, and .env* files

Approval workflow

When a policy requires approval:

1. Agent's action is captured and stored securely
2. Task appears in the workspace Inbox → Approvals queue
3. An authorized reviewer (member with the approver role) sees the action summary and a preview of changes
4. Reviewer can approve (action proceeds) or reject (agent is notified, no changes applied)
5. Approvals expire after 7 days; expired requests are marked expired and must be resubmitted

Approving an action

To approve a pending action:

1. Open Inbox → Approvals
2. Click the pending action to see the full diff and context
3. Click Approve to proceed, or Reject to deny
4. If approved, the agent's queued payload is applied immediately
5. If rejected, the agent is notified and can adjust its approach

Policy effects

require_approval

When a policy's effect is require_approval:

• Agent's action is queued and not applied
• Workspace members with the approver role receive an approval request
• Action only proceeds after explicit approval
• Useful for safeguarding important config or high-stakes changes

deny

When a policy's effect is deny:

• Agent's action is rejected outright
• No approval request is created
• Agent is notified with the denial reason
• Useful for absolute blocklists (e.g., secrets or credentials)

Best practices

• Start conservative — enable templates for CI/CD and secrets, then refine as needed
• Use path globs carefully — **/billing/** is overly broad; prefer billing/pricing.json or similar
• Set clear priorities — avoid confusion when multiple policies might apply
• Review denials regularly — if agents are frequently hitting deny policies, consider whether the rule needs adjustment
• Communicate to your team — make sure squad leads know which paths require approval

Next steps

• Enterprise governance features — workspace-wide security controls
• Safe outputs layer — how approval policies integrate with agent output handling
• Members and roles — understand approver role requirements