Skip to content

Docs / Escalations

Escalations

When the agent pages a human: security, breaking changes, and stuck threads.

Escalations

Some situations require a human decision. The maintainer agent recognises these automatically and pauses until a maintainer responds — it never acts unilaterally on sensitive work.

Built-in escalation categories

These categories always escalate, regardless of your .maintainer.yml policy. They cannot be disabled:

Category Trigger
security Any issue or PR with a CVE, CWE, security label, or keywords like "vulnerability", "RCE", "SSRF", "injection".
license A PR adds a dependency with an incompatible or unknown SPDX licence.
cla A contributor's CLA is missing and CLA enforcement is enabled for the repo.

Configurable always escalations

Add categories to escalate.always to get the same hard-pause behaviour for your own triggers:

escalate:
  always: [security, license, cla, compliance]

Custom categories match against issue labels, PR labels, and the first 500 characters of the issue or PR body. Matching is case-insensitive substring.

ask_before_acting escalations

These pause the bot and ask the maintainer for explicit approval before continuing. Unlike always, the bot does not email immediately — it posts a comment and waits.

Built-in ask_before_acting categories:

Category Trigger
breaking PR title or commit messages contain BREAKING CHANGE or ! suffix (feat!).
major Version bump in package.json, Cargo.toml, etc. crosses a major boundary.
first-time-contributor Author has never had a PR merged in this repo.
large PR diff exceeds pr.large_threshold_lines (default 500).

Add your own in .maintainer.yml:

escalate:
  ask_before_acting: [breaking, major, first-time-contributor, large, database-migration]

How escalation works

  1. Detect — the agent matches the issue, PR, or event against the escalation rules.
  2. Comment — the bot posts a disclosure comment explaining exactly why it paused and what it needs from the maintainer.
  3. Email (always only) — a digest email is sent immediately for hard-pause categories.
  4. Wait — the agent parks the thread and does nothing until a maintainer replies or applies an approved label.
  5. Resume — once approved, the agent continues the loop from the paused step.
  6. Audit — every escalation event (trigger, pause, approval, resume) is written to the audit log with actor and timestamp.

Bot-on-bot safety

The agent detects comments from CodeRabbit, Copilot, Dependabot, and Renovate and defers to them rather than creating conflicting threads. Configure the list via pr.wait_for_other_bots.

The agent never responds to itself. A comment from developerz[bot] does not trigger another loop iteration.

Overriding an escalation

Post a comment on the issue or PR with one of:

  • /approve — approve this action and continue the loop.
  • /skip — dismiss the escalation and close the thread without acting.
  • /close — close the issue or PR (maintainer only).

Overrides are logged with the author's GitHub login and timestamp.