Governance Policies
Many integrations ship only read tools, so an agent can't write to them at all. Where an integration has write tools, an agent can call them only if its tool filters keep them. Governance policies add approval gates on top: each policy pauses a matching tool call until a person approves it. With no policies configured, every tool call an agent is allowed to make runs without approval, so most organizations start with a policy on Operation type is write.
Configure them in each project under Settings → Agent policies. The page lists the project's policies in a table that you can search by name and sort. Each row shows:
- the policy's name, with its conditions on a line under it;
- Approvers: who can approve the calls it pauses, or Anyone when the policy doesn't limit it;
- Applies to: the integrations its conditions match today;
- when it was last updated, and a switch that turns it on or off.
A warning icon before the conditions marks a policy that needs an edit: its conditions can never match the same integration, or a condition names a label key that no longer exists. Hover the icon for the reason.
Create policy opens a new, empty policy. Each row opens that policy's own page, where you edit it and save it without touching any other policy.
How policies are evaluated
A tool call needs approval if any enabled policy matches it. Policies do not override one another, and their order in the list is display only, so sorting the list never changes whether approval is required.
Within a single policy, every condition must match. A condition can list several values, and it matches when any of them does. The policy's page shows one condition per line, and each field is a field of the integration the call touches:
WHEN Type is
githubORaws
AND Operation type iswrite
That policy pauses writes to GitHub and AWS integrations and nothing else. To cover one more integration, add its type to the same condition. A second condition "Type is datadog" would make the policy match nothing, because no integration has two types. To gate two unrelated things, such as GitHub writes and every call to an integration labeled prod, write two policies.
Among the tool calls an agent is permitted to make, those that match no policy run without approval. With no policies configured at all, nothing is gated.
Condition fields
Every condition describes the integration the tool would touch, or the kind of operation. There are no conditions on which user or which agent is running. A policy applies to every agent in its project.
| Field | Matches on | Example value |
|---|---|---|
| Type | The integration's type | datadog, github, kubernetes |
| Name | A specific integration instance | datadog-prod |
| Operation type | Whether the tool reads or writes | read, write |
Label · <key> | A label on the integration | environment is prod |
A tool can touch more than one integration. A few tools call a second integration besides their own: Okta's Send a temporary password sets the password in Okta and sends it by Slack DM. Each integration is checked on its own, with its own type, name, labels and operation type, so a policy on either one pauses the call: "Type is okta, Operation type is write" does, and so does "Type is slack, Operation type is write". The approval shows every integration the call touches, and such a call is always approved once — Allow for session is not offered. All conditions of one policy are checked against the same integration, so a single policy cannot require "Okta and Slack"; it does not need to. An agent's tool filters work differently: a filter sees only the tool's own integration, so integration_type != "slack" does not remove Send a temporary password from an agent.
Operators are is and is not. is matches when the field is any of the condition's values, and is not matches when it is none of them. With several values, the page reads them as "Type is github or aws" and "Type is neither github nor aws". Values are matched exactly and are case-sensitive. For example, Prod does not match prod. There are no wildcards or patterns.
"Operation type is write" is broader than it looks. The platform treats tool calls that it cannot confidently classify as writes. A policy that gates writes will therefore also catch unclassified operations. This is deliberate. It fails toward asking a human rather than acting unattended. But it means that such a policy may pause more than you expect.
Labels
Label conditions behave differently from the other fields in two ways worth knowing.
A label condition only applies to integrations that carry that label. Given a policy with the condition "environment is not prod":
| Integration | Matches? |
|---|---|
environment = staging | Yes: has the label, value differs |
environment = prod | No: value matches, so "is not" fails |
No environment label at all | No: the policy skips it entirely |
So a policy phrased as "anything that isn't production" will not cover unlabeled integrations. This is intentional: silently including everything unlabeled surprises people. If you want unlabeled integrations governed too, add a separate policy that matches on type or operation type instead.
Labels can hold several values. A condition is a membership test, not an equality test. For an integration labeled environment = [prod, us-east], the condition "environment is prod" matches, and "environment is not prod" does not. With several values in the condition, "environment is prod or staging" matches an integration whose label carries either one, and "environment is neither prod nor staging" matches one whose label carries neither.
Label keys may contain letters, digits, and underscores, and must not begin with a digit. You cannot use a key like env-name in a policy. You can use env_name.
Add labels to integrations on the Integrations page before writing policies that depend on them.
What happens when a policy matches
The tool call is paused before it runs. Nothing reaches your systems while the decision is outstanding, and the agent waits rather than failing.
An approver can:
- Allow once: this single call proceeds.
- Allow for session: this call proceeds. Later calls to the same tool on the same integration within that agent session skip the gate. This option is only offered for straightforward commands. Anything that combines multiple commands, redirection, or wrapper invocations can only be approved once. This way, approving one thing cannot quietly authorize another.
- Reject: the call does not run. The agent receives the reason you give. It typically adapts its approach rather than retrying the same call.
Pending approvals never expire. There is no timeout and no automatic denial. A tool call waits indefinitely until someone decides. An agent run that appears stalled may be waiting on an approval.
Who can approve
By default, anyone who can approve calls in the project can approve a call that a policy pauses. To limit this, add people or user groups to the policy's Approvers. Then only those people, and the members of those groups, can approve a call that the policy pauses. For example, add your IT lead to a policy on "Type is okta, Operation type is write" so that only they can approve changes to Okta.
- The limit applies to approving only. Anyone who can approve calls in the project can still reject the call.
- If two or more policies pause the same call, the approver must be on the Approvers list of each policy that has one. A policy with an empty list adds no limit. The order of the policies in the list does not change this.
- An approver also needs permission to approve calls in the project (see Permissions). The Approvers list limits who can approve. It does not give permission to approve.
- Allow for session applies only where the person who chose it can approve. If a later call in that session is paused by a policy with an Approvers list, and that person is not on the list, the call waits for approval again.
- A paused call keeps the Approvers lists that were set when the agent made the call. If you change a list, the change applies to calls that the policy pauses after you save.
- You can add only people who have a role in your organization, and user groups of your organization. Service accounts cannot approve calls, so you cannot add them to the list.
- If nobody on a paused call's lists can approve it any more (for example, the person left the organization or the group is empty), reject the call. Then fix the Approvers list and ask the agent to try again. The new call uses the new list.
Managing policies
Disable a policy to pause it: turn off its switch in the list or on its page. It stays in the list with its configuration intact and stops gating tool calls immediately. Use this rather than deleting when you may want the policy back.
Delete is permanent. The policy is removed entirely and cannot be recovered. If you need it again, recreate it from scratch. Deleting frees its name for reuse. Disabling does not.
Editing a disabled policy keeps it disabled.
Each policy also takes an optional note, shown to whoever reviews an approval. Use it to record why the policy exists.
If two admins edit the same policy at once, the second save is refused rather than silently overwriting the first. Reload the page and reapply your change.
API and CLI
You can also manage policies with the Autoheal CLI (autoheal agent-policies) or the /api/v1/agent-policies API. They use these names for what the page shows:
| On the page | In the API and CLI |
|---|---|
| Type | integration.type |
| Name | integration.name |
| Operation type | operation_type |
Label · <key> | label.<key>, for example label.environment |
| is | equals |
| is not | not_equals |
| The values of a condition | values, a list such as ["github", "aws"] |
| Approvers | approvers: user ids and user group ids (grp_…) |
This creates a policy that pauses every write to a GitHub or AWS integration. Save the policy as policy.json:
{
"name": "Approve GitHub and AWS writes",
"note": "Changes to code and cloud need a second pair of eyes.",
"conditions": [
{ "field": "integration.type", "operator": "equals", "values": ["github", "aws"] },
{ "field": "operation_type", "operator": "equals", "values": ["write"] }
]
}
A condition can also give one value instead of values, as files written for earlier versions do: "value": "write" is read as "values": ["write"]. A condition can't have both. Responses always use values.
Then create it in the CLI's project (--project-id names another):
autoheal agent-policies create --input policy.json
autoheal agent-policies list shows each policy with its id. update <id> changes only the fields you send (--field enabled=false disables a policy), and delete <id> deletes one. update-all replaces the project's whole set: it deletes every policy its file leaves out and saves every policy in it enabled. Run autoheal agent-policies --help for every command. A script can call the API with an API key or personal access token.
Limits
| Maximum enabled policies per organization (all projects combined) | 100 |
| Conditions per policy | At least one, with no upper limit |
| People and user groups in Approvers | Up to 20 per policy |
| Policy names | Required, and unique within a project across enabled and disabled policies |
| Values per condition | 1 to 50, each 1 to 256 characters, none listed twice |
Permissions
Managing policies and approving individual calls are separate permissions. A Member can clear an approval without being able to change the policies. A policy's Approvers list can limit approving further (see Who can approve).
| Project Admin | Member | Read-only | |
|---|---|---|---|
| View policies | yes | yes | yes |
| Create, edit, delete policies | yes | ||
| View pending approvals | yes | yes | yes |
| Approve or reject a call | yes | yes |
See Roles & Permissions for the full permission model.