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

# Automations

> Run agents on a schedule or in response to GitHub, GitLab, Slack, Sentry, or custom webhook events.

Automations let you run Replicas agents automatically, on a schedule, in response to GitHub or GitLab events, when messages are posted in Slack channels, or whenever any external system hits a custom webhook URL. Use them for nightly maintenance, scheduled audits, automatic responses to PR activity, reacting to messages in Slack, wiring up a tool we don't have a first-class integration for, and any other workflow you want to run without a human in the loop.

<Note>
  Automations and the [public API](/features/api) are the **only** sanctioned channels for programmatic use of Replicas. Driving the dashboard, Slack, Linear, GitHub, or CLI from scripts is prohibited under our [Terms of Service](https://tryreplicas.com/terms).
</Note>

## How it works

Each automation has:

* A **prompt** the agent will receive when the automation runs.
* An **[environment](/features/environments#attaching-an-environment-to-an-automation)** that supplies the repository (or repository set) plus any vars / files / skills / MCPs layered on top of Global.
* One or more **triggers** that decide when the automation fires.
* An optional **debounce** window, in seconds. When set, bursty trigger events update one pending run for the automation; the latest payload runs after the automation stops receiving events for that many seconds.
* Optional **coding agent** (Claude Code, Codex, Cursor, Opencode, or Pi), **model**, and **thinking level** overrides. The `ultra` level is Codex-only, and `ultracode` is Claude Code-only. Leave any of them unset to fall back to your organization's default agent and the agent's own default model and thinking level.
* Optional [**plan**](/features/workspaces/plan-mode), **goal**, and [**fast**](/features/workspaces/fast-mode) mode overrides. Leave goal or fast mode unset to inherit your organization's defaults. Plan mode applies to Claude, Codex, Cursor, and Opencode; goal mode only applies to Codex; fast mode applies to Codex and Claude Opus models.
* A **workspace size** (`small` or `large`). Defaults to `small` (2 vCPU, 8 GB memory, 20 GB disk). Pick `large` (4 vCPU, 16 GB memory, 32 GB disk) for memory or CPU-bound work; see [Billing](/admin/billing) for per-size rates.
* A **workspace lifecycle**: archive when done, sleep when done, or stay alive until a configurable inactivity timeout. Automations never delete a run's workspace on a timer, so a run stays inspectable from the run history (archived workspaces may still be removed later by the retention policy, after 30 days dormant). Sleeping and archived workspaces do not count toward usage.

When a trigger fires, Replicas creates a fresh workspace, sends the prompt to the configured coding agent, and tracks the run as an **execution** you can review in the dashboard.

New workspaces use the automation's name. If another unarchived workspace from the same automation exists, the new run adds a five-character suffix, such as `Daily Overview (fvjw3)`.

## The automation editor

The create and edit form leads with the four things an automation actually needs: a **Name**, plus its **Triggers**, **Instructions**, and **Environment** (ordered **when → what → where**). Everything else is optional tuning.

* **Capability palette.** Below the Instructions field, a row of capability chips (Slack, Linear, Google, Docker, screenshots, previews, and more) surfaces what the agent can do beyond editing code. Clicking a chip appends a starter line for that capability to the instructions and marks the chip as added, so you can discover and wire up abilities without writing the prompt from scratch.
* **Advanced settings.** The optional tuning (debounce, workspace lifecycle, workspace size, agent & model, and PR follow-ups) is collapsed behind a single **Advanced settings** toggle, so first-time authors aren't faced with every option at once. Each setting keeps its default until you expand and change it; the toggle shows a `· customized` hint when any advanced value differs from its default.

## Personal automations

By default, automations are org-owned and visible to all members. You can also create **personal automations** that are scoped to your user account:

* Only you can view, edit, trigger, or delete your personal automations
* Workspaces created by personal automations are attributed to you
* Personal automations still count toward your organization's plan quota (max automations and executions per hour)

Use personal automations when you want workspace runs attributed to you (e.g. personal PR review bots, individual triage workflows) without exposing them to the rest of the org.

Create a personal automation in the dashboard via the **Your Automations** tab, or via the [API](/features/api) by setting `scope: "user"` in the create request. The [CLI](/features/cli) supports `--personal` on `replicas automation create`. Personal automations require user-level authentication (JWT or personal API key).

List automations by ownership with the `scope` query parameter:

* `scope=org` (default) - org-owned automations only
* `scope=user` - your personal automations only
* `scope=all` - both org automations and your personal automations

## Triggers

Six trigger types are supported today:

### Cron triggers

Run an automation on a recurring schedule defined by a standard cron expression. The minimum interval is **60 minutes** between runs.

### GitHub triggers

Run an automation in response to events from your connected GitHub repositories. You can optionally filter a GitHub trigger to a specific subset of repositories.

Supported events:

* **PR opened**: fires when a pull request is created
* **PR updated (new commits)**: fires when new commits are pushed to a pull request
* **PR merged**: fires when a pull request is merged
* **PR closed**: fires when a pull request is closed or merged (includes merges for backwards compatibility)
* **PR command (`/replicas run`)**: fires when someone comments a `/replicas run` command on a pull request (see [Triggering from a pull request](#triggering-from-a-pull-request))

GitHub triggers support the following optional settings:

* **Exclude users**: Events sent by these GitHub usernames never fire the automation. Useful for ignoring bots like `dependabot[bot]` or teammates whose PR activity shouldn't spawn runs. Matching is case-insensitive and ignores a leading `@`.
* **Group PR events**: Available on **PR opened**, **PR updated (new commits)**, and **PR command**. When enabled, later events (or repeat commands) for a PR that already has a workspace from a prior run of the same automation route to that workspace as a follow-up message instead of spawning a new one. Works the same way as Slack's [Group thread replies](#slack-triggers).

Automation workspaces have no attached user and fall back to the Replicas bot for PR attribution.

<Note>
  **Skip automations on a single PR.** To stop automations from *automatically* firing on one specific pull request (without disabling the automation for everyone), add the label `replicas-skip` to the PR, or include a marker like `[skip replicas]` in the PR title or body. This mirrors the `[skip ci]` convention and works the same way for GitLab merge requests (`replicas-skip` label or `[skip replicas]` in the MR title/description). Accepted labels: `replicas-skip`, `skip-replicas`, `replicas-ignore`, `no-replicas`. Accepted title/body markers: `[skip replicas]`, `[replicas skip]`, `[no replicas]`.

  The marker suppresses event-driven runs (PR opened, updated, merged, closed). Explicitly asking for a run still works and overrides the marker. A [`/replicas run` command](#triggering-from-a-pull-request) or a manual **Run** from the dashboard/API runs regardless, since those are deliberate on-demand actions. The same marker also silences [PR auto-respond](/features/github#silence-replicas-on-a-single-pr).
</Note>

### GitLab triggers

Run an automation in response to events from your connected GitLab projects. You can optionally filter a GitLab trigger to a specific subset of projects.

Supported events:

* **MR opened**: fires when a merge request is created
* **MR updated (new commits)**: fires when a merge request is updated
* **MR merged**: fires when a merge request is merged
* **MR closed**: fires when a merge request is closed

GitLab triggers support the following optional settings:

* **Exclude users**: Events sent by these GitLab usernames never fire the automation.
* **Group MR events**: Available on **MR opened** and **MR updated (new commits)** only. When enabled, later opened or updated events for an MR that already has a workspace from a prior run of the same automation route to that workspace as a follow-up message instead of spawning a new one.

<Note>
  When a GitHub PR or GitLab MR trigger starts a workspace, Replicas adds one shared automation comment to the PR or MR. Each matched automation links to its automation page and latest workspace; repeated runs update that automation's existing entry instead of posting another comment.
</Note>

### Slack triggers

Run an automation when a new message is posted in a connected Slack workspace. You can optionally filter to specific channels. For example, only fire when someone posts in `#nit`. Bot messages and message edits are automatically ignored.

Slack triggers support one optional setting:

* **Group thread replies** (on by default): When a top-level message creates a workspace, subsequent replies in that thread are routed to the same workspace instead of spawning new ones. Turn this off if you want each message to always create its own workspace, regardless of threading.

<Note>
  Slack triggers require your organization to have Slack connected in **Organization → Integrations**. The Slack app must be subscribed to `message.channels` events in the app configuration.
</Note>

### Sentry triggers

Run an automation in response to events from your connected Sentry organization. You can optionally filter to specific Sentry projects, and set a minimum severity level so only events at or above the chosen level fire the automation.

Supported events:

* **Issue alert fired** (`event_alert.triggered`): fires when one of your Sentry issue alerts is triggered.
* **New issue created** (`issue.created`): fires when Sentry opens a new issue.
* **New error event** (`error.created`): fires when a new error event is captured.

<Note>
  Sentry triggers require your organization to have Sentry connected in **Organization → Integrations**. See [Sentry](/features/sentry) for how to connect.
</Note>

### Custom webhook triggers

If none of the built-in triggers fit your use case, add a **custom webhook** trigger. Replicas generates a unique URL for the automation, and anyone with the URL can fire it by sending an HTTP `POST` with any JSON body:

```bash theme={null}
curl -X POST https://api.tryreplicas.com/v1/automations/webhook/whtok_xxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"anything": "you want", "nested": {"too": true}}'
```

The request body is parsed as JSON (non-JSON bodies are wrapped as `{ "raw": "<body>" }`) and embedded into the automation's prompt under `## Trigger Payload`, so your prompt can reference any fields the caller sent.

The endpoint returns `202 Accepted` once the execution is queued. It does not wait for the workspace to spin up, so callers stay fast. Disabled automations, unknown tokens, and automations without a custom trigger all return `404` without distinguishing between the three.

The URL itself is the secret. Treat it like an API key: don't check it into public repos or share it in logs. If the URL leaks, remove the custom trigger and re-add it to rotate the token.

Each trigger event can only be added once per automation. You can still combine distinct events, for example a GitHub `pull_request.opened` trigger plus a GitLab `merge_request.opened` trigger, but not two `pull_request.opened` triggers.

## Triggering from a pull request

Add the **PR command (`/replicas run`)** event to a GitHub trigger to make an automation runnable on demand from any open pull request in the connected repositories. Comment on the PR:

* `/replicas` lists the automations available on that PR, each with its comment command and a one-click **Run** link into the dashboard.
* `/replicas run <command>` runs that automation against the PR. The command is the automation's name lowercased with spaces and punctuation replaced by dashes (for example, **Code Review** becomes `/replicas run code-review`).

Replicas reacts with 👀 once the run starts, or replies with the reason when it can't start. The PR's repository, number, and URL are injected into the prompt context, exactly like event-driven PR triggers. Unknown commands get a reply listing the available automations. With **Group PR events** enabled on the trigger, repeat commands for the same PR flow to the existing workspace as follow-ups instead of starting new runs.

Commands are honored only for members of your Replicas organization (or senders on the auto-respond allowlist); the trigger's repository filter and excluded users apply as usual. Unlike `@replicas` mentions, `/replicas` commands never spawn a PR chat workspace.

PR command automations can also be run via the [API](/features/api): `POST /v1/automations/:id/trigger` with `{ "pr": { "repository_id": "<uuid>", "number": 123 } }`.

## Debouncing

Add a debounce window to any automation to collapse duplicate trigger bursts into one delayed run.

When a matching event arrives, Replicas schedules one pending run for that automation. GitHub and GitLab runs are scoped to the repository and pull or merge request, so activity on another request cannot replace them. Additional matching events in the same scope update the pending run with the latest payload and push the timer out again. Leave debounce blank or set it to `0` to run every trigger immediately. The maximum window is 24 hours.

## GitHub checks

Give an automation a list of GitHub check names and every matching pull request gets those checks reported directly on the commit, so a run's verdict is a merge gate instead of a comment someone has to read.

The checks are **created in progress** the moment the PR event lands, before the workspace exists and before any [debounce](#debouncing) window elapses, and only the agent's final result completes them. That ordering is what makes them safe to mark **required** in a GitHub ruleset:

* A required check can never be silently missing while Replicas is still working.
* A required check cannot pass while it is still running, so a review in flight blocks the merge just as a failure would. A run that fails to start, gets rate limited, or dies mid-review is completed as a failure with the reason, rather than left spinning.
* Exactly one run reviews a commit at a time. Repeat events on the same commit reuse the same check runs rather than stacking up duplicates, and an event arriving while a run still owes that commit a verdict is dropped instead of started alongside it. Once the checks carry a result, a later event takes them over and reviews the commit again.
* A verdict from a run that has since been superseded is discarded rather than applied, so the check always reflects the newest review of the commit.

Names are configured under **Advanced settings → GitHub Checks** in the automation editor, or with `github_check_names` via the [API](/features/api#create-an-automation) and `--github-checks` via the [CLI](/features/cli#automations). Up to 10 names, and the automation needs a **PR opened** or **PR updated (new commits)** trigger, since those are the only events that carry a head commit to attach a check to.

For expensive checks that should only run once, configure **PR opened** without **PR updated (new commits)**. Replicas automatically creates the same checks on later head commits without starting another automation run. An opening review still in progress stays in progress on the current head; its final verdict is copied over when ready. Each inherited check says which opening commit was reviewed and that the later commit was not tested.

Adding **PR updated (new commits)** disables carry-forward because the automation runs and reports fresh checks for each new head instead. Manual PR command triggers can coexist with automatic carry-forward.

### Reporting a verdict

The agent is told which check runs it owns and reports each one through Replicas rather than writing to GitHub itself:

```bash theme={null}
replicas automation check <check run id> --token <token> --conclusion success --title 'No duplicated logic' --summary 'Reviewed the diff; nothing reinvents an existing utility.'
```

The token comes from the prompt and names the run the verdict belongs to, which the check run ID cannot: a workspace reused for a follow-up event holds checks from more than one run on the same commit. Replicas verifies the token still owns the check and then writes it, holding the same lock every other writer takes. Routing the write through the server is what makes the verdict safe: a workspace cannot hold that lock, and GitHub has no conditional write on check runs, so an agent writing directly could always be overtaken between checking ownership and writing.

<Note>
  If a check name cannot be created on GitHub, the run is not dispatched at all. Failing to start is preferable to running with a pull request that looks unguarded.
</Note>

### Adding checks to existing automations

Automations created before checks existed report nothing until you give them names. Both surfaces an agent can drive, the [CLI](/features/cli#automations) and the [API](/features/api#automations), can do this without the dashboard.

Find the candidates, then add names to each:

```bash theme={null}
replicas automation list --trigger-type github
replicas automation edit <id> --add-github-checks "DRY Check"
```

The listing shows the checks each automation already reports on, and `--add-github-checks` keeps them, so a pass over every automation cannot drop a name somebody else configured. Use `--github-checks` instead to replace the list outright. Over the API, `PATCH /v1/automations/:id` takes `github_check_names` and replaces it, so read the current values first if you mean to add.

## Pull request management

Automations are read-only toward matching pull requests by default: they can react to PR events and create a workspace, but they do not register those PRs as Replicas-managed. This is only about PR routing: an automation can always push branches and open pull requests.

Enable **Allow PR follow-ups** when an automation should run follow-up behavior on matching PRs. This stores `config.capabilities.pr_followups: true` and snapshots that config onto each run and workspace, so later CI and review-comment replies can route back to the automation workspace.

Automation API clients can set the same behavior through `config.capabilities.pr_followups`. Replica API clients can also set this workspace capability when creating a replica. Leave it omitted or `false` when matching PRs should not route events back.

To stop an automation from writing code at all, turn on **Read-only repository contents** under **Advanced settings → Repository Access**, or set `config.capabilities.read_only_contents: true` over the API. Its GitHub token then carries read-only repository contents while keeping write access for PR comments, issues, and checks, so a review automation can report a verdict but cannot push. Required PR user attribution still applies to those reports.

Automation config is also copied to each workspace created by the automation, including workspace preferences like `config.preferences.keep_open_on_pr_merge` and `config.preferences.keep_open_on_pr_close`.

## Plan availability and limits

Automations are available on every plan. Plans differ only in rate limits and the per-cycle pool of included minutes (see [Billing](/admin/billing)).

| Plan       | Max automations | Org executions / hour | Per-automation executions / hour | Min cron interval |
| ---------- | --------------- | --------------------- | -------------------------------- | ----------------- |
| Free trial | Unlimited       | Unlimited             | Unlimited                        | 60 minutes        |
| Developer  | 5               | 20                    | 5                                | 60 minutes        |
| Team       | Unlimited       | Unlimited             | Unlimited                        | 60 minutes        |
| Enterprise | Unlimited       | Unlimited             | Unlimited                        | 60 minutes        |

Trial orgs get 15,000 automated minutes for the whole trial, shared with the API. Automation runs are blocked once that cap is reached or the trial ends.

## Reliability

Every execution is recorded with its status (`pending`, `creating`, `running`, `completed`, or `failed`) and any error message. Automations remain enabled regardless of failures, and continue to fire on their configured triggers until you manually disable them.

In the dashboard, open an automation and select a failed execution's error to view the complete message and copy it for debugging.

When a Slack-triggered automation fails during workspace startup, initial task delivery, or agent execution, Replicas replies with the concrete error in the originating thread. For GitHub and GitLab triggers, the shared automation comment or note shows the failure in that automation's entry. Direct workspace requests from GitHub comments, GitLab notes, and Linear agent sessions also show startup and execution errors in their integration activity. Sentry, cron, and custom webhook failures remain available in the execution history because those triggers do not provide a native reply surface.

## Billing

Automation workspaces are metered separately from your seat subscription. Each workspace is billed at the rate of the **size** it was created with (`small` or `large`), so a fleet that mixes both bills at a mixture of the two rates. See [Billing](/admin/billing) for rates, rounding, and plan details.

Personal automation workspaces still use automation metering. They carry the owner's `user_id` for auth, credentials, attribution, and security policy checks, but they do not become seat-billed workspaces.

## Templates

The automations page surfaces a small set of starter templates with their tags and [triggers](#triggers) pre-filled, so you can stand up a useful automation in a few clicks instead of writing a prompt from scratch.

Available templates today:

* **Code Review.** Posts a single PR comment with an X/5 review score on PR opened and synchronized.
* **DRY Code Check.** Flags duplicated logic, parallel schemas, and reinvented utilities on PRs.
* **No Unused Code.** Flags code that became unused as a result of the PR.
* **No useEffects Check.** Catches unnecessary `useEffect` escape hatches in React PRs.
* **Unnecessary Comments Check.** Flags comments that restate code instead of explaining the non-obvious "why".
* **Unnecessary TypeScript Casting.** Challenges avoidable `as any`, non-null assertions, and `@ts-ignore` escape hatches in TypeScript PRs.
* **Documentation Sync.** Verifies that docs and the changelog stay in sync with feature changes.

Selecting a template opens a read-only preview. Click **Use this template** to seed the create form with the template's name, description, triggers, and prompt. You still pick the environment the automation should run in, which supplies the repository (or repository set) it targets.

Have a suggestion for a new template? Send it to [founders@replicas.dev](mailto:founders@replicas.dev).

## Related resources

* [Code review follow-up](https://tryreplicas.com/use-cases/code-review-follow-up)
* [Backlog cleanup](https://tryreplicas.com/use-cases/backlog-cleanup)
* [Automated bug fixes](https://tryreplicas.com/use-cases/automated-bug-fixes)

## Managing automations

Automations can be created, updated, listed, and triggered from the dashboard, the [CLI](/features/cli#automation-management), or via the same REST API and API key as the rest of the [public API](/features/api). You can also fire an automation on demand from the dashboard or CLI to test that it works without waiting for the next scheduled or webhook-driven run.

Use the Automations page tabs to switch between organization automations and automations you own in the current organization. In the API, pass `scope: "user"`. In the CLI, `replicas automation create --personal` creates a personal automation and `replicas automation list --owner user` lists personal automations.