> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaegis.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Policies

> Understand Aegis policies: what they are, how the 10 built-in rules work, how to enable or disable them, and how policy state is stored.

A **policy** in Aegis is a rule that Aegis evaluates against every incoming MCP tool call before that call reaches GitHub. When a tool call matches a policy's conditions, Aegis assigns the decision type defined by that policy, ALLOW, DENY, REWRITE, or REQUIRE\_APPROVAL. Policies run in sequence on every action, so a single tool call may be evaluated against all 10 rules before a final outcome is determined.

Policies are user-scoped. Each Aegis account has its own policy state, meaning you can configure which rules are active independently from other members in a room.

## Policy categories

Policies are grouped into four categories that reflect their purpose:

| Category       | Focus                                                                |
| -------------- | -------------------------------------------------------------------- |
| **Governance** | Branch strategy, PR workflow, naming conventions, and freeze windows |
| **Safety**     | Preventing autonomous merges, requiring CI, gating large changes     |
| **Compliance** | Secret detection and credential scanning                             |
| **Access**     | Repository allowlisting                                              |

## Built-in policies

<AccordionGroup>
  <Accordion title="Protected Branch Denial, REWRITE (Governance)">
    **Key:** `protected_branch_denial`

    Direct writes to `main`, `master`, and release branches are redirected to a safe pull request workflow instead of being blocked. The agent's tool call succeeds, but the outcome is a PR rather than a direct commit. This preserves agent velocity while enforcing code review on protected branches.
  </Accordion>

  <Accordion title="Freeze Window Enforcement, DENY (Governance)">
    **Key:** `freeze_window_enforcement`

    Write actions that occur during a configured release freeze window are blocked. You define freeze windows separately; this policy is what causes Aegis to enforce them at the tool call level. Any write attempted during an active window receives a DENY with a message indicating the freeze.
  </Accordion>

  <Accordion title="Aegis Branch Naming, DENY (Governance)">
    **Key:** `aegis_branch_naming`

    All branches created by agents must follow the `aegis/{session_id}/{task}` naming convention. Attempts to create branches that do not match this pattern are denied. This makes it easy to identify agent-created branches in your repository at a glance.
  </Accordion>

  <Accordion title="Mandatory PR Flow, REQUIRE_APPROVAL (Governance)">
    **Key:** `mandatory_pr_flow`

    Every agent write action must result in a pull request. When this policy is active, write tool calls are held for human review before execution. This gives you a review gate on every proposed change, regardless of the target branch.
  </Accordion>

  <Accordion title="No Autonomous Merge, DENY (Safety)">
    **Key:** `no_autonomous_merge`

    Agents cannot merge pull requests without explicit human approval. Any merge attempt is blocked. This policy is the last line of defense against agents landing code into your codebase without oversight.
  </Accordion>

  <Accordion title="CI Required Before Merge, DENY (Safety)">
    **Key:** `ci_required_before_merge`

    Merge attempts are blocked if CI checks have not passed on the pull request. Aegis checks the CI status before forwarding the merge tool call and denies it if any required check is failing or pending.
  </Accordion>

  <Accordion title="Repo Allowlist, DENY (Access)">
    **Key:** `repo_allowlist`

    Agents can only write to repositories that have been explicitly approved in your Aegis configuration. Write tool calls targeting any repository outside the allowlist are blocked. This prevents agents from accidentally, or maliciously, committing to repositories they should not touch.
  </Accordion>

  <Accordion title="Sensitive Path Approval, REQUIRE_APPROVAL (Safety)">
    **Key:** `sensitive_path_approval`

    Changes to high-risk file paths require a human to approve before execution. Protected paths include CI/CD pipeline definitions, infrastructure-as-code, and authentication configuration. When an agent targets one of these paths, the action is queued for review.
  </Accordion>

  <Accordion title="Secret Detection, DENY (Compliance)">
    **Key:** `secret_detection`

    Every diff proposed by an agent is scanned for API keys, tokens, and credentials before it reaches GitHub. If a potential secret is detected, the action is blocked. This prevents agents from accidentally committing credentials that were injected into context or generated as part of a task.
  </Accordion>

  <Accordion title="Blast Radius Gate, REQUIRE_APPROVAL (Safety)">
    **Key:** `blast_radius_gate`

    Actions whose blast radius is assessed as `High` or `Critical` are held for human approval before execution. Large source changes, such as bulk file rewrites, widespread refactors, or infrastructure modifications, require you to explicitly authorize them before they land.
  </Accordion>
</AccordionGroup>

## All policies at a glance

| Policy                    | Key                         | Effect            | Category   |
| ------------------------- | --------------------------- | ----------------- | ---------- |
| Protected Branch Denial   | `protected_branch_denial`   | REWRITE           | Governance |
| Freeze Window Enforcement | `freeze_window_enforcement` | DENY              | Governance |
| Aegis Branch Naming       | `aegis_branch_naming`       | DENY              | Governance |
| Mandatory PR Flow         | `mandatory_pr_flow`         | REQUIRE\_APPROVAL | Governance |
| No Autonomous Merge       | `no_autonomous_merge`       | DENY              | Safety     |
| CI Required Before Merge  | `ci_required_before_merge`  | DENY              | Safety     |
| Repo Allowlist            | `repo_allowlist`            | DENY              | Access     |
| Sensitive Path Approval   | `sensitive_path_approval`   | REQUIRE\_APPROVAL | Safety     |
| Secret Detection          | `secret_detection`          | DENY              | Compliance |
| Blast Radius Gate         | `blast_radius_gate`         | REQUIRE\_APPROVAL | Safety     |

## Enabling and disabling policies

You manage policies from the **Policies** page in the Aegis dashboard.

<Steps>
  <Step title="Open the Policies page">
    Navigate to **Dashboard → Policies**. The page lists all 10 policies with their name, category, effect, and a toggle showing whether each is currently active.
  </Step>

  <Step title="Toggle individual policies">
    Click the toggle on the right side of any policy row to enable or disable it. Disabled policies are dimmed. The header shows a running count of how many policies are active out of 10.
  </Step>

  <Step title="Save your changes">
    Click **Save Changes** in the top-right corner of the page. Aegis writes your updated policy state to the backend. A confirmation appears briefly when the save succeeds. Changes take effect immediately for all subsequent tool calls.
  </Step>
</Steps>

<Warning>
  Disabling safety-critical policies like Secret Detection or No Autonomous Merge reduces your governance coverage. Only disable policies if you have an explicit reason and understand the risk.
</Warning>

## Custom policies

The 10 built-in policies cover the most common governance scenarios, but every organization has unique requirements. If you need a policy tailored to your workflows, custom path rules, organization-specific branch patterns, or integration with internal systems, contact the Aegis team.

<Note>
  To discuss custom policies, reach out to [deals@runaegis.com](mailto:deals@runaegis.com).
</Note>