# Automations

> Let a channel act on its own — reply to patterns, run on a schedule, react to PRs, and hand work to an agent behind your approval.

An automation is a small rule that lives in one channel: when something
happens, the channel acts. The channel's agent posts the reply or reaction,
and anything that would cost money — an agent actually doing work — waits for
a person to approve it first.

Automations run within about a minute of their trigger.

## Build one

1. Open the channel menu (the channel's name in the header) and choose
   **Automations**.
2. **New automation** — name it, pick a trigger, add what happens.
3. Save. The rule is live; the toggle on the list turns it off any time.

Creating and editing automations is for workspace admins. Everyone in the
channel can open the list and see what's automated and when it last ran.

The same controls are available to a personal coding connection. Use
`list_automations`, `save_automation`, `set_automation_enabled`, and
`delete_automation` over MCP, or the matching `/api/v1/channels/:id/automations`
REST endpoints. Each connection stays inside the workspace it was created for,
and a channel's definitions and run history follow that channel's visibility.

## Triggers

- **A message matches** — a substring to look for, optionally only messages
  with a file attached. The automation never reacts to its own output, so
  two automations can't chase each other.
- **On a schedule** — every N minutes (15 at the least). A re-enabled or
  newly created schedule waits for its next boundary; it never replays what
  it missed.
- **A PR merges** / **Checks fail on a PR** — from the channel's linked
  repo, at the moment GitHub reports it. Checks fire on genuine failures
  only, once per commit, however many webhook events GitHub sends.
- **A task completes** — when a task pinned to this channel is set to done,
  from any direction: the tracker, an agent, or a PR merging. Once per task,
  ever — reopening and re-completing stays quiet.
- **A run finishes** — an agent's run in this channel reaches its end,
  however it ended: a PR ready for review, finished clean, failed, timed out,
  or canceled. Once per run, ever — a run that ships a PR fires at the review
  gate, not again when the PR merges. `{{text}}` carries the run's own line
  ("Forge's run finished — awaiting review, https://github.com/…/pull/812").
- **A webhook calls** — anything that can POST fires it. Saving gives you a
  URL and a key, shown once; send `{"text": "…"}` and `{{text}}` carries it.
  Calls are rate-limited, and a repeated `x-delivery-id` never fires twice.

## What happens

- **Reply** — a templated message. `{{author}}`, `{{text}}`, and
  `{{channel}}` fill in from the trigger; on repo events `{{text}}` carries
  the event itself ("Checks failed on PR #41 → lint"). Optionally reply in
  the triggering message's thread.
- **React** — an emoji on the triggering message.
- **Ask an agent** — the differentiator. The automation files a task with
  your prompt and proposes dispatching it to the agent you chose. The
  proposal appears in the channel as the usual routing card; the agent only
  starts when someone approves it there. An automation can ask — it can
  never spend.

So "when checks fail, ask Forge to investigate" means: CI fails, a task is
filed with the failure details, Forge is proposed, and the run starts the
moment a person approves — with the same report card and review gate as
any other agent run.

## Run history

Each automation keeps its recent runs — every step, whether it ran, and why
it didn't ("no agent member to act as", "no message to react to"). Open the
automation to see them.