Beta Coming soon. This feature is still being built, so names and details may change before it ships.

Automations

Automations start an agent on a pull request, a comment, a CI failure, a Slack message, a Linear issue or comment, a webhook or a schedule, and keep it working until a goal is met.

Each automation is a Markdown file in .ingot/automations/, so it lives in your repository and is reviewed like code. It runs in the open Ingot IDE (run: local) or on an Ingot cloud agent while the IDE is closed (run: cloud).

The Automations panel: three automations with their triggers and goal, and the history with Goal met and DoneThe Automations panel: three automations with their triggers and goal, and the history with Goal met and Done
The Automations panel: three automations with their triggers and goal, and the history with Goal met and Done

An automation file

---
name: Fix failing CI
on: [ci_failure]
branches: [main]
run: local
goal: CI passes again
done_when: [the failing tests pass locally, no unrelated changes]
check: npm test
max_iterations: 3
---
CI failed: {{title}}.
Find the failing job, reproduce it locally, make the smallest safe fix and run the tests again.

The file name is the automation's id (fix-ci.md is fix-ci). The text after the frontmatter is the prompt. {{title}}, {{body}}, {{branch}}, {{base}}, {{url}}, {{author}}, {{number}}, {{repo}}, {{workflow}}, {{sha}} and {{channel}} are filled in from the event, and for Linear also {{identifier}} (ENG-42), {{team}}, {{state}} and {{labels}} (comma-separated). Text from outside (a PR body, a comment, a Slack message, a Linear issue) is fenced as untrusted data, so the agent never follows instructions hidden inside it.

KeyDefaultWhat it does
onrequiredone or more triggers (below)
runlocallocal: the open IDE starts an agent chat. cloud: an Ingot cloud agent run
enabledtruefalse keeps the file but never starts it
repothis project's originowner/name: only events from that GitHub repository
branchesanybase branch globs for pr, head branch globs for ci_failure
pr_actionsopened, reopened, ready_for_reviewalso synchronize, edited, closed
mention@ingotcomment needs this text; "" means any comment
workflowsanyci_failure: workflow or check name globs
slack_channel, keywordanyslack: one channel (#eng or C0123…); keyword must appear in the message (also for webhook, and for linear.* in the issue title, description or comment)
linear_labelsanylinear.*: label name globs. The issue needs at least one matching label
linear_teamsanylinear.*: team key globs (ENG, WEB)
linear_statesanylinear.*: workflow state name globs (Todo, In Progress)
cron, timezonecron: five fields (0 3 * * *) or @daily; at least 5 minutes apart. The cloud uses UTC unless timezone is set
cooldown10minutes before the same automation starts again
modelthe defaultthe model for the agent

Triggers

TriggerStarts on
pra pull request opened, reopened or ready for review (GitHub pull_request)
commenta PR or issue comment, or a review comment, that mentions @ingot
ci_failurea failed or timed-out GitHub Actions run or check (workflow_run, check_run, check_suite)
slackan @Ingot mention, a /ingot slash command, or a channel message with the keyword
webhooka POST to the automation's webhook URL (any JSON or text)
cronthe schedule
linear.issue_createda new Linear issue
linear.issue_updatedany change to a Linear issue: state, labels, title, assignee…
linear.comment_createda new comment on a Linear issue

Events sent by bots, or by Ingot itself, never start an automation, so an automation can't trigger itself in a loop. The same delivery (the same CI run, comment or PR update) starts an automation only once. See Start from Linear for the Linear triggers.

Hold a goal until it is met

With goal, the agent keeps working until the goal is met or it has used max_iterations turns (default 5, at most 20):

  1. The agent works on the prompt, with the goal and the done_when criteria in view.
  2. Ingot runs check (a command such as npm test). It must exit 0.
  3. If it fails, the agent gets the check's output and tries again.
  4. The fire ends as Goal met, or Gave up when the turns run out.

In the IDE this is the chat's goal mode: the goal banner shows each criterion, the check result and the turns used. In the cloud, every try is a new run that starts with the failing check's output.

An automation's chat in the IDE: the goal check failed, then passed, and the goal banner says DoneAn automation's chat in the IDE: the goal check failed, then passed, and the goal banner says Done
An automation's chat in the IDE: the goal check failed, then passed, and the goal banner says Done

In the IDE

Open Automations in the bottom panel (⌥⇧N on Windows and Linux, ⌘⌥⇧N on macOS). It lists each automation with its triggers, where it runs and its goal, and the history of every fire: what started it, the turns used and the result. Show Chat opens the agent chat of a fire.

ActionmacOSWindows / Linux
Automations panel⌘⌥⇧NAlt+Shift+N
New Automation… (from a template or a blank form)⌘⌥⇧CCtrl+Alt+Shift+C
Run Automation Now…⌘⌥JCtrl+Alt+J
Send Test Event to Automations…⌘⌥GCtrl+Alt+G

Every action is also in Find Action, with Copy Automation Webhook URL, Copy GitHub Webhook Secret for Automations, Set Slack Signing Secret for Automations, Set Linear Signing Secret for Automations, Sync Cloud Automations, Reload Automations and Clear Automation History. Settings are under Settings › Automations: the on/off switch, the local receiver and its port (7391), how many automations may run at once (2) and notifications.

GitHub, Slack and webhooks

Local automations listen on a receiver inside the IDE at http://127.0.0.1:7391:

  • /github: add a GitHub webhook (repository Settings › Webhooks) with content type application/json and the secret from Copy GitHub Webhook Secret. Choose Pull requests, Issue comments, Pull request review comments, Workflow runs and Check runs.
  • /slack: the Events API request URL and slash command URL of your Slack app; set its signing secret with Set Slack Signing Secret for Automations.
  • /linear: the URL for a Linear webhook. See Start from Linear.
  • /hooks/<id>: any tool can POST here with the token in Copy Automation Webhook URL (Authorization: Bearer <token> or ?token=).

GitHub and Slack can't reach 127.0.0.1 directly: forward with a tunnel (for example gh webhook forward), or use run: cloud.

Cloud automations have public URLs on the Ingot server. Sync Cloud in the panel (or ingot automations sync) uploads the run: cloud files and shows the URLs:

HookURLSigned with
GitHub/api/bot/automations/hooks/<key>/githubyour GitHub webhook secret (X-Hub-Signature-256)
Slack/api/bot/automations/hooks/<key>/slackyour Slack app's signing secret
Webhook/api/bot/automations/hooks/<key>/hooks/<id>your webhook token

Unsigned calls are refused. Cloud automations need a plan with Zaprex cloud agents (Silver, Gold or Platinum), and they use its minutes, approvals and limits.

Start from Linear

Three triggers start an agent from Linear: linear.issue_created, linear.issue_updated and linear.comment_created. Removed issues and edited or deleted comments are ignored. Changes made by integrations, OAuth apps or Ingot itself never start an automation.

Narrow them down with linear_labels, linear_teams, linear_states and keyword. Matching ignores case, and * and ? work like they do in branches. When you set several filters, all of them have to match.

  • linear.issue_updated fires on every edit. Pair it with linear_labels or linear_states so it only runs where you want it. The cooldown stops it from running again for the same issue too soon.
  • Linear doesn't always send the state or labels with a comment. A comment automation with linear_states or linear_labels then won't match, so filter comment automations by linear_teams or by nothing.

The agent's prompt always includes the issue identifier, its title, its URL and the description. Comment events give the comment text, plus the issue description when Linear sends it. Text from Linear is fenced as untrusted data, like PR bodies and Slack messages. New Automation… and automations new --template linear-issue start from a Linear issue template.

Set up the Linear webhook

Linear reaches local automations (run: local) only. Cloud automations don't take Linear events yet.

  1. Forward the receiver through a tunnel (for example ngrok http 7391 or cloudflared tunnel --url http://127.0.0.1:7391), because Linear can't reach 127.0.0.1.
  2. In Linear, open Settings › API › Webhooks and choose New webhook. Set the URL to <tunnel URL>/linear, pick the team (or all public teams) and the data types Issues and Comments.
  3. Copy the webhook's Signing secret. In Ingot, click Linear in the Automations panel (or run Set Linear Signing Secret for Automations…) and paste it.
  4. Add an automation with a linear.* trigger. Create or label an issue to test it, or choose Send Test Event › Linear issue created.

Ingot checks the Linear-Signature header, the HMAC-SHA256 of the raw body made with the signing secret. It refuses calls with a missing or wrong signature, and calls whose webhookTimestamp is more than five minutes old. Without a saved secret, /linear answers 503.

Example: fix bugs labeled ingot

.ingot/automations/linear-bugs.md:

---
name: Fix Linear bugs labeled ingot
description: When an ENG issue gets the ingot label, try a fix and open a PR.
on: [linear.issue_created, linear.issue_updated]
linear_teams: [ENG]
linear_labels: [ingot]
linear_states: [Todo, Backlog]
goal: the bug is fixed and covered by a test
check: npm test
max_iterations: 4
cooldown: 60
---
Work on Linear issue {{identifier}} ({{url}}): {{title}}

{{body}}

Reproduce the problem, make the smallest safe fix, add a test, and open a pull request
whose title starts with {{identifier}} so Linear links it.

Example: answer @ingot in Linear comments

---
name: Linear @ingot comments
on: [linear.comment_created]
linear_teams: [ENG]
keyword: "@ingot"
---
Someone asked for help on Linear issue {{identifier}} ({{url}}).
Do what the comment asks and summarize what changed.

{{body}}

From the terminal

npx @ingotide/cli automations                     # list: triggers, where each runs, goal, next run
npx @ingotide/cli automations validate            # check every file; exits 1 on errors (CI)
npx @ingotide/cli automations new --template fix-ci
npx @ingotide/cli automations test --github workflow_run payload.json --show-prompt
npx @ingotide/cli automations sync                # upload run: cloud automations
npx @ingotide/cli automations run fix-ci          # Run Now in the cloud
npx @ingotide/cli automations fires               # recent cloud fires and goal tries

test runs offline: it shows which automations a sample GitHub, Slack, webhook or schedule event starts, and why the others don't. The cloud commands need a personal access token (--token or INGOT_TOKEN). Every option is on CLI.

Safety

  • An automation's agent has the same tools, sandbox and approvals as a chat you start yourself; a risky step still waits for your approval.
  • At most 2 local automations run at once (Settings › Automations); an event that arrives while they are busy is skipped, and the sender is told why.
  • Turn every automation off in Settings › Automations, or one with its checkbox in the panel (this sets enabled: false in the file).
  • Secrets live in the IDE's key store or encrypted on the server, never in the files.