Skip to main content

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 github OR aws
AND Operation type is write

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.

FieldMatches onExample value
TypeThe integration's typedatadog, github, kubernetes
NameA specific integration instancedatadog-prod
Operation typeWhether the tool reads or writesread, write
Label · <key>A label on the integrationenvironment 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.

warning

"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":

IntegrationMatches?
environment = stagingYes: has the label, value differs
environment = prodNo: value matches, so "is not" fails
No environment label at allNo: 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.
note

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 pageIn the API and CLI
Typeintegration.type
Nameintegration.name
Operation typeoperation_type
Label · <key>label.<key>, for example label.environment
isequals
is notnot_equals
The values of a conditionvalues, a list such as ["github", "aws"]
Approversapprovers: 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:

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):

BASH
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 policyAt least one, with no upper limit
People and user groups in ApproversUp to 20 per policy
Policy namesRequired, and unique within a project across enabled and disabled policies
Values per condition1 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 AdminMemberRead-only
View policiesyesyesyes
Create, edit, delete policiesyes
View pending approvalsyesyesyes
Approve or reject a callyesyes

See Roles & Permissions for the full permission model.