Automations
An automation points Auditor's agent at recurring work: a trigger, an instruction in your words, the repositories it applies to, how far it may go and what it may post. One firing runs once per repository in scope, every run is billed to the team's Auditor key like a review, and each run is a conversation you can watch, send notes to and continue.
What an automation is
Automations live at Team → Auditor → Automations and are defined once for the team, not per repository. Each one has a trigger (a schedule, a pull request event or a push), a scope (which repositories), an instruction, a permission (read, propose or push), outputs (a comment, an issue, a pull request), a budget and, if you want one, a model of its own. Owners and admins create and edit them; anyone who manages a repository can opt that repository out or replace the instruction for it from the repository's settings drawer.
When it fires, Auditor runs the agent once per repository in scope, each run on its own: it reads the repository at the right commit with the same tools the fix command uses (read a file, search the code, list a folder), edits files when the permission allows, and ends with a summary and whatever the automation may post. The automation's page shows the last firing as a table across its repositories: what each produced, what it cost and how long it took.
Triggers
| Trigger | When it fires | Filters |
|---|---|---|
| Schedule | Every hour, day, week or month at a time in a timezone you pick. Each tick is one firing across the scope; a big scope runs through the queue at eight repositories a minute. Never more often than hourly. | Day of the week or of the month, hour and minute. |
| Pull request | A pull request is opened, marked ready for review, pushed to, or labeled. The run looks at the pull request's head commit and can comment on it. | Head and base branch patterns, changed paths, labels, title patterns, and whether drafts count. |
| Push | A push to a branch. The run looks at the pushed commit. By default the default branch only. | Branch patterns and changed paths. |
| Check failed | A GitHub Actions workflow run, or any other CI's check, ends in failure (not cancelled or skipped). The run looks at the failing commit and gets the failed job's log around the first error, or the check's own output; on a pull request it can comment there. | Workflow or check name patterns, branch patterns, and whether only failures on pull requests count (the default) or anywhere. |
| Issue | An issue is opened or labeled. The run looks at the default branch and gets the issue's title and text; a comment goes on the issue, and a proposal is a pull request against the default branch. | Labels, title patterns and authors. Pull requests have their own trigger and never count here. |
| Webhook | A POST to the automation's own firing URL, from anything that can send one: a Shopify webhook, a deploy hook, a script. It fires on every repository in scope, like a schedule tick, with the request's JSON body as data for the agent. The URL carries a token shown once when the automation is saved; Rotate on the automation's page makes a new one. | None. Send the token as Authorization: Bearer or ?token=. |
Patterns are globs, as in .rules/ matchers: release/*, src/**. Events the Auditor bot itself causes never fire an automation, and a branch an automation opened (auditor/auto-…) is neither reviewed nor a trigger, so an automation cannot set itself or another one off. Run now fires an automation by hand on every repository in scope or on one, and Dry run does the same without writing anything to GitHub: the run's record says what it would have posted. From a pull request, @auditor automation <name> in a comment runs the team automation of that name on that repository with the pull request as its subject (anyone with write access to the repository; @auditor run works too).
Check-failure and issue triggers need the GitHub App to receive those events and to read Actions logs. The platform's app has them; a team's own white-label app made before they were added gets them when its owner approves the updated permissions in the app's settings on GitHub. A GitHub Actions failure fires once, through its workflow run, even though GitHub also reports it as a check.
Scope and repositories
Scope is one of three: every repository switched on for Auditor, including ones installed later; repositories whose full name matches a pattern (acme/*-theme matches by the full name or by the name alone); or a list you pick from the repositories table, with the same search and account filters as the Auditor page. The scope is resolved when the automation fires, so a repository turned on for Auditor tomorrow is in tomorrow's firing.
A schedule or webhook automation can instead run on the repositories together: one run, one agent, reading every repository in scope at once (up to 10), for a shared library and the projects that use it, say. Every tool then takes a repository argument, each repository the agent edits gets its own pull request against its default branch and the pull requests name each other, and the issue goes in the first repository. Pull request, push, check and issue triggers always run per repository, since the event belongs to one. Proposals across repositories are not checked in a Sandbox.
Each repository's settings drawer has an Automations tab listing the team's automations and whether the repository is in scope. There, anyone who manages the repository can turn an automation off here, or replace the team's instruction with the repository's own words; the automation's page shows which repositories did either.
The instruction
The instruction is Markdown in your words, up to 8,000 characters: what to look for, what counts, what to do about it and what to leave alone. The agent also gets the repository's conventions for coding agents (AGENTS.md, CLAUDE.md, and the like) and, on a pull request, the pull request's description, its changed files and its ticket when a tracker is connected.
Everything the run reads apart from your instruction and your messages to it is treated as data: code and comments, commit messages, pull request and issue text, ticket text. The agent is told so, and nothing it reads can widen what the automation may do; the permission and the outputs are fixed on the automation. A run that finds nothing to do says so and posts nothing.
Permission
| Permission | What the agent may do |
|---|---|
| Read | Read and search the repository. Can comment and open issues. Never edits a file. The default. |
| Propose | Edit files on a new branch and open a pull request against the branch the run is about. Never pushes to that branch itself. |
| Push | Edit files and push to the branch the run is about: a pull request's head, or the pushed branch. Not available on a schedule, which has no branch to push to. |
Before a proposal's pull request opens, the edits are checked in a Sandbox with the repository's own static tools (the type checker, the linter, Semgrep, Theme Check for a theme), as @auditor fix checks a fix. What they report on the changed lines goes back to the agent for one more round; the pull request then opens with a line saying what was checked and what still reports. The check follows the team's Check fixes setting; without it, or when no tool applies to the changed files, the pull request opens unchecked and says so.
Edits are collected and committed only if the agent proposes a pull request in its answer; otherwise they are dropped and the run says so. Whatever the permission, the agent never edits .github/, lockfiles or generated files, and changes at most 12 files in a run. Propose and Push use the GitHub App's write permission on contents and pull requests. An installation made before that permission existed approves it in the app's settings on GitHub; until then a run that tries to commit says the permission is missing and keeps the rest of its answer.
Outputs
Outputs are what the automation may post: a comment on the pull request the run is about (on a schedule or a push there is none, so the comment stays in the run's record), an issue in the repository, or a pull request with the agent's edits. The agent may suggest more than the automation allows; anything not allowed is recorded on the run but not posted. A read-only automation cannot have the pull request output.
Everything posted carries a footer naming the automation (under your own name with the white label add-on), and the run's page links to it.
Four more channels reach beyond GitHub:
| Channel | What it does | What it needs |
|---|---|---|
| Tracker | The agent's comment goes on the ticket the pull request names, in Linear, Jira or Shortcut; the agent's issue becomes a tracker issue when the automation names a Linear team key, a Jira project key or a Shortcut project id. A later turn comments on the issue it opened instead of opening another. | A tracker connected under Ticket links on the Auditor page, with a token that can write. |
| Email digest | One email per firing, once every run of it has finished: each repository's outcome and summary, with links to what was posted. For a pull request or push trigger that is one email per run. | Addresses, or none for the team's owners and admins. |
| Slack | The same digest as one Slack message per firing. | An incoming webhook URL for the channel, from Slack's app settings. Stored sealed; never shown again. |
| Webhook | One POST per run with the run, its answer and what it produced, as JSON. Signed as X-Auditor-Signature-256: sha256=<HMAC of the body> when a secret is set. | An https URL, and a signing secret of at least 16 characters if you want the signature. |
Digests are never sent for a dry run, which records what each channel would have received instead.
Budget, model and limits
Each run is billed as inference to the team's Auditor key, like a review, under session = the run id in Logs; the automation's page shows this month's spend. Every automation has a per-run budget (default $2): when a run reaches it, the agent is told to stop and answer with what it has. An optional monthly budget per automation skips firings once it is reached, and the team's Auditor spend caps apply on top. The model is the team's find model unless the automation names one; either way it has to be allowed by the team's Directives.
Protections against a loop or a flood: one live run per repository and subject (a pull request, a branch, or the automation itself on a schedule); at most 20 automation runs an hour per repository across the team's automations; a schedule over many repositories is spread at eight a minute. A skipped run says which rule skipped it.
Runs and the conversation
Open a run from the automation's table (or the last run from the repository drawer) and you see it as a conversation: where the agent is looking, each tool call with its result, the agent's reasoning and its answer, as they happen. While a run is queued or working, Send note reaches the agent before its next step, worded as part of your instruction (“only look at src/, skip tests”), and Stop makes it answer with what it has so far.
Once the agent has answered, Continue takes a reply and queues another turn on the same commit, with the agent's edits still in its workspace and the whole conversation in its context. What it posts adds to what the run already produced rather than repeating it: more commits on the pull request it opened, a comment on the issue it opened, another comment on the pull request. Each turn has the per-run budget. Notes and replies are your words, so they are part of the instruction; they cannot change the automation's permission or outputs.
The run's record keeps the conversation, what it produced with links, its cost, its model calls and a Logs link to the requests. A dry run has the same conversation and ends with what it would have posted.
Recipes
The editor starts blank, with six recipes beside it and more under More recipes: triage failed GitHub Actions, fix CI failures, triage Linear issues, triage Jira issues, find vulnerabilities, flaky tests, a slow test report, an issue labeled for the agent, dependency advisories, secrets in pull requests, and for Shopify themes: API deprecations, store drift, theme performance regressions and docs drift. A recipe fills the trigger, the instruction, the permission and the outputs; change any of it before saving. The Linear and Jira recipes fire on a pull request that names a ticket; triggers from the trackers themselves are planned.