Automations
Run the project agent automatically on a trigger, with scoped permissions and explicit MCP Server access.
An automation runs the project agent for you on a trigger. Instead of opening a chat and asking, you define the work once and let it fire whenever the right thing happens in your project. Each automation has a name, one or more triggers, a prompt it runs on every fire, a model, optional permission restrictions, and optional access to MCP Servers.
An automation runs as a specific user, the run-as user, and inherits that user's permissions. Every run is a full agent conversation you can open, read, and continue.
What an automation contains
| Part | What it does |
|---|---|
| Triggers | One or more events, or a schedule, that start a run |
| Prompt | The instruction the agent runs on every fire |
| Model | The model the run uses. Defaults to Auto |
| Restrictions | Optional limits that narrow what the automation can create or edit |
| MCP Servers | Optional external services the automation is allowed to reach |
| Run-as user | The owner whose permissions the automation inherits |
Triggers
A trigger decides when an automation runs. A single automation can hold several triggers at once, so one automation can respond to more than one kind of event.
Use the Add Trigger picker to add triggers. Event triggers are grouped by module, while Code Push and Scheduled are their own entries.
| Trigger | Fires when | Configuration |
|---|---|---|
| Code Push | Connected code is re-indexed after a push | Pick one or more repositories, or leave it as any connected codebase |
| Knowledge Base Document Created | A new Knowledge Base document is created | None |
| Knowledge Base Document Edited | A Knowledge Base document is saved with changes | None |
| Requirement Created | A new requirement is created | None |
| Requirement Edited | A requirement is saved with changes | None |
| Blueprint Created | A new blueprint is created | None |
| Blueprint Edited | A blueprint is saved with changes | None |
| Work Order Created | A new work order is created | None |
| Work Order Edited | A work order changes status or receives a label | Status changed to chosen statuses, or Label added for a chosen label |
| Feedback Created | A new feedback item is submitted | None |
| Scheduled | A cron schedule comes due | A preset (Hourly, Daily, Weekly), or a Custom cron expression |
Code Push
Code Push fires after connected code is re-indexed following a push. Use the repository multi-select to scope it to specific repositories, or leave it empty. Leaving it empty means any connected codebase, including repositories you connect later.
Work Order Edited
Work Order Edited can be configured two ways:
- Status changed: choose which target statuses fire it, from Backlog, Ready, In Progress, In Review, Blocked, Completed, and Cancelled. Leaving the statuses empty means any status change fires it.
- Label added: choose a specific work order label, or any label.
Scheduled
Scheduled runs the automation on a cron schedule. The builder offers presets for Hourly, Daily, and Weekly, plus Custom for a raw cron expression.
There is no timezone picker. When you set a preset time, the builder shows it in your own browser's timezone and converts it to UTC when the automation is saved, so the schedule fires at the same absolute moment no matter where a teammate later opens it. A Custom cron expression is stored and interpreted as UTC.
Edited triggers fire on saved versions
The edited triggers, such as Knowledge Base Document Edited, Requirement Edited, Blueprint Edited, and Work Order Edited, fire once per saved version, not on every keystroke while someone is typing. Each run receives the before and after of that change, so the agent can compare the current version against the previous one and act on the difference.
Recommended automations
The Automations page shows a Recommended catalog of ready-made automation templates alongside the automations your project has already created. Each card carries an Add button and a count of how many templates you have added so far.
Selecting Add opens the builder pre-filled from that template. When you save it, you get a normal, enabled automation that you own and can edit like any other. The catalog tracks which templates you have added, and offers Update on a card when a newer version of a template you added becomes available.
Every automation, whether you build it from scratch or add it from the catalog, is owned by its run-as user. That owner can edit or delete it, and anyone with Owner access to the project, including organization Admins, can edit or delete any automation.
What's in the catalog
- Check Blueprint References runs on Blueprint Edited. It finds dependent blueprints and leaves flagged comments where they may have drifted. It never edits the documents.
- Sync Blueprints and Requirements runs on Blueprint Edited and Requirement Edited. It flags drift between a feature's requirements and its linked blueprint.
- Detect Code Drift runs on Code Push. It reviews changed files against the code linked to your blueprints and reports drift, delegating per-blueprint analysis to sub-agents.
- Triage Feedback runs on Feedback Created. It reads each item, matches it to a theme, and extracts representative quotes.
Permissions and restrictions
An automation always runs with the run-as user's own permissions. Restrictions can only narrow what it may create or edit. They can never widen its access beyond what that user already has.
The Restrictions section states this in product: "Automations inherit your permissions. Configure any restrictions below." Use Add Restriction to add a limit for a domain. You can restrict these seven domains:
- Knowledge Base
- Requirements
- Blueprints
- Work Orders
- Feedback
- Themes
- Comments
Each restriction takes one of two levels:
| Level | Effect |
|---|---|
| Cannot create | Can still edit existing items in that domain |
| Cannot edit or create | Fully read-only for that domain |
The default when you add a restriction is Cannot edit or create. A common pattern is to restrict every domain an automation should only observe, so it can comment and act within its lane without changing documents. For example, an automation that closes the loop on completed work can restrict Blueprints, Requirements, Work Orders, Feedback, and Themes to Cannot edit or create, leaving it free only to comment.
Watch for self-triggering loops
If an automation is triggered by a domain it can also write to, it can trigger itself in a loop. When this is possible, the builder warns you while you author and suggests adding a restriction on that same domain. Adding a Cannot edit or create restriction on the watched domain clears the warning. This is why the Recommended automations that watch a domain, such as Check Blueprint References, hold a read-only restriction on it and only leave flagged comments.
MCP Servers
An automation reaches external services only through the MCP Servers you explicitly grant it. With no grants, it cannot reach any external service at all. Connect MCP Servers under Settings → Connections → MCP Servers, then grant the ones an automation needs.
This is different from the interactive chat agent, which uses your own personal connections. An automation runs headless, so it must be given each MCP Server it needs. For example, an automation that posts a summary to a team chat channel needs that chat MCP Server granted before it can deliver anything outside the project.
When you author an automation by chat, the agent first lists your connected MCP Servers and asks which to grant before it creates the automation.
Model
Each automation runs with a selectable model. The default is Auto, which picks a suitable model for you. You can choose a specific model instead when a run needs it.
Run history
Every run of an automation is a full agent conversation. The run history lists each run with its outcome, and opening a run shows the complete transcript of what the agent did, including its messages and its tool activity. After a run finishes, you can continue the conversation with a follow-up.
Each automation shows 30-day totals of successful, failed, and total completed runs, so you can see at a glance how it is doing.
Disabling is safe
Disabling an automation stops future trigger-driven runs. Any run already in progress is allowed to finish.
Authoring an automation
There are a few ways to create an automation.
Build it visually (Create)
Select Create to open the visual builder, the primary way to create an automation in the app. Add triggers, write the prompt, pick a model, set any restrictions, and grant the MCP Servers it needs, then save. You can also reach the builder pre-filled by adding a Recommended automation.
Ask the agent (propose, then Create or Cancel)
Describe the automation you want in plain language, and the project agent builds it. It does not assume defaults for your triggers, restrictions, or MCP Server grants. It asks you to choose each one, then proposes the finished automation for you to Create or Cancel before anything is created.
Create it programmatically (MCP or the External REST API)
Over the software-factory MCP server, create_automation_v2 creates the
automation immediately, enabled and owned by the caller. The External REST API
is a separate surface with its own automations endpoints. Either way, each
request states its triggers, restrictions, and MCP Server grants up front. Use
edit_automation to change an existing automation in place rather than
creating a duplicate.
Recipes
These patterns are drawn from automations running in real projects. Adapt the triggers, prompts, and restrictions to your own setup.
Triage feedback the moment it arrives
- Trigger: Feedback Created.
- Prompt: read the new feedback item, match it to the right theme, and pull representative quotes.
- Restrictions: Cannot edit or create on Requirements, Blueprints, and Work Orders, so the automation only touches feedback and themes.
- MCP Servers: none.
Weekly release notes on a schedule
- Trigger: Scheduled, cron
0 13 * * 5(Fridays at 13:00 UTC). - Prompt: draft the next release notes, add a comment that mentions each workstream lead for review, and post a link in your team's chat channel asking for a review.
- MCP Servers: grant your chat MCP Server. External delivery always needs an explicit grant.
Build a work order when it gets a label
- Trigger: Work Order Edited with Label added, scoped to one specific label.
- Prompt: pick up the labeled work order, implement it, move it through In Progress and In Review, open a pull request, and narrate progress in the work order comments.
- Restrictions: consider a Work Orders restriction if the automation should not re-trigger itself on its own status changes.
Keep blueprints honest
- Trigger: Blueprint Edited.
- Prompt: find dependent blueprints and flag where they may have drifted.
- Restrictions: Cannot edit or create on Blueprints, so the automation only leaves flagged comments. This mirrors the Recommended Check Blueprint References.
Best practices
- Give each automation a narrow job. One clear trigger and one clear prompt are easier to trust than a broad catch-all.
- Restrict the domains an automation only needs to read. A read-only lane prevents accidental edits and clears self-trigger warnings.
- Grant only the MCP Servers an automation truly needs, and only when it delivers something outside the project.
- Start from a Recommended automation when one fits. Add it, watch a few runs, then build your own when you need something the catalog does not cover.
- Read the run transcripts. They show exactly what the agent did and are the fastest way to tune a prompt.
Want to see how much your automations are running? Review usage.