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

# Automations

> Rule-based background workflows: a trigger fires, an agent session or built-in action runs, and guardrails gate anything that publishes externally.

**Automations** are rule-based background workflows. Each rule pairs a **trigger** — a schedule, an event, or a webhook — with an **execution surface**, then runs either a scoped AI chat session or a sequence of deterministic built-in actions. **Guardrails** gate anything that would publish externally, so a low-confidence or unreviewed run never writes to GitHub, Linear, or the web on its own.

Automations sit between the CTO (heavy, stateful, chat-driven) and raw cron (deterministic, no AI). They're for the repeatable background work you'd otherwise do by hand — a nightly audit, a review on every PR, a summary when a chat ends.

> [!NOTE]
>
> The **Automations** tab is rolling out. In production builds it currently shows a **"Soon"** badge while the surface lands — the rule engine and run history described here are how it works once enabled.

![The Automations builder in ADE](https://mintcdn.com/ade-ac1c6011/Mghbi7-G0yTaUGxT/media/current/automations.jpg?fit=max\&auto=format\&n=Mghbi7-G0yTaUGxT\&q=85\&s=9e893f968dfcbac9691587513b004dee)

The automation builder: a trigger, its execution surface, and the guardrails that gate it.

## Anatomy of a rule

> [card] Trigger
>
> What starts the rule — a cron schedule, an action event, or an inbound webhook.

> [card] Execution surface
>
> Either an `agent-session` (a scoped AI chat) or `built-in` (deterministic ADE actions).

> [card] Guardrails
>
> Confidence threshold, human review, path/lane allowlists, and optional agent time limits.

> [card] Output
>
> Where results go — a comment, a follow-up lane or task, a draft PR, or evidence only.

## Triggers

A rule fires from one of three broad classes of trigger.

> [tab] Time-based
>
> A 5-field cron schedule (minute, hour, day-of-month, month, day-of-week). Seconds aren't supported. The editor previews the next fire time.
>
> ```text theme={null}
> 0 9 * * 1-5   # weekdays at 09:00
> ```

> [tab] Action events
>
> Git and lifecycle events: `git.commit`, `git.push`, `lane.created`, `lane.archived`, `file.change`, `session-end`, and `manual`. GitHub events cover PR and issue lifecycle (`github.pr_opened`, `github.pr_merged`, `github.issue_opened`, `github.issue_labeled`, and more), with filters for labels, authors, target branch, repo, and title/body regex.

> [tab] Webhooks & Linear
>
> Inbound `webhook` and signed `github-webhook` events, plus `linear.*` events consumed as context. GitHub events arrive over a real webhook, a relay, or direct polling — matching is identical regardless of source.

> [!NOTE]
>
> Linear triggers here are **context only**. There is no autonomous issue-routing engine — automations react to Linear events for their own work, and any Linear write is an explicit rule action. See [Linear](https://ade-app.dev/docs/integrations/linear.md).

## Execution surfaces

Choosing the surface is the key decision — it sets how much orchestration a rule carries.

> [card] agent-session
>
> A scoped AI chat thread with the rule's prompt and allowed tools. Best for reviews, audits, and short summaries. Appears in run history as a thread.

> [card] built-in
>
> A sequence of deterministic ADE actions — create a lane, run a command, run tests, predict conflicts, or dispatch an allowlisted ADE action. No AI in the loop; sandboxed to the target lane's worktree.

> [!TIP]
>
> Built-in actions are deterministic by design — they shouldn't wrap an AI call. When a step needs reasoning, use an `agent-session` (a built-in chain can embed one as a step).

## Guardrails

Automations publish effects — comments, PRs, Linear updates, webhooks. Guardrails decide whether a run is allowed to publish, or whether it parks in a review queue first.

| Guardrail | What it does |
| - | - |
| Confidence threshold | A run below the threshold (baseline \~0.65) lands in review instead of publishing. |
| Require human | Force human review regardless of confidence. |
| Verify before publish | The run must pass a verification step — or a reviewer's approval — before external effects apply. |
| Path / lane allowlists | Built-in shell and file actions are sandboxed to specific lane worktrees or subpaths. |

### Time limits

An automation's agent has **no time limit by default**. Like a chat you start yourself, it runs until the work is done — a release that waits an hour on CI and notarization is fine. If you want a backstop, open **Limits** on the agent step:

* **Stop after** — end the agent's turn after this many minutes, whatever it is doing.
* **Stop when idle for** — end it after this many minutes with no activity. Waiting on a command, a tool, a subagent working in the foreground, or an approval does not count as idle; background tasks and long silent thinking can, so leave some room.

Either one interrupts the agent and keeps its chat open. A **Run command** step has its own **Time limit** (default 5 minutes) that stops the command if it hangs.

Each rule also carries a **review profile** (quick, incremental, full, security, release-risk, cross-repo-contract) that sets the base confidence — `security` and `release-risk` start higher than `quick`.

> [!NOTE]
>
> Runs that need a human land in a queue with statuses like **pending review**, **verification required**, and **completed clean**. The dashboard shows a severity summary so you can triage without opening every run.

### Secrets and scope

> [card] Env-ref secrets only
>
> Webhook secrets and access tokens must be `${env:VAR_NAME}` references — raw secret values are rejected and resolved at run time.

> [card] Sandboxed actions
>
> Built-in shell actions stay inside the allowed workdirs; paths that escape the lane worktree or project root are rejected.

## Authoring a rule

You can write a rule from a free-text brief — a planner turns the brief into a draft rule (triggers plus actions) that you review before saving — or build it directly in the rule editor by picking a trigger, an execution surface, and guardrails. Templates seed a new draft to start from.

> [!TIP]
>
> Use the **simulate** path to dry-run a rule against a synthetic trigger before enabling it — it lists exactly which actions would fire, with nothing published.

> [card] [CTO overview](https://ade-app.dev/docs/cto/overview.md)
>
> The persistent project-level operator with durable memory.

> [card] [Linear](https://ade-app.dev/docs/integrations/linear.md)
>
> Attach issues, link PRs, and read issues from ADE.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.