gitstalk docs automations

Automations live

An automation is an agent defined by a file in .gitstalk/automations/. It runs when something happens in the repository, on a schedule or by hand, in a fresh container with a memory of its own, and it may propose fixes as beans.

Live on the hosted service since 9 October 2026. The browser builder is beta.

An example

This one wakes when a bean's pre-land check goes red, and every Monday at 09:00 UTC. It may push fix beans as itself and may spend up to 50 cents a run.

name: Fix red beans
on:
  bean_red:                     # a bean's pre-land check went red
  schedule: [{ cron: "0 9 * * 1" }]
permissions:
  beans: write                  # may push fix beans as itself
max-cost-usd: 0.50
prompt: |
  Read why the bean went red. Check your memory for this failure.
  Fix it in a new bean and note what you tried and learned.

A .md file works too: YAML front matter between --- lines, and the body is the prompt. Push the file as a bean. It goes live when the stalk takes it.

What you see

Triggers bean_red, schedule 0 9 * * 1
Runs     a prompt on @cf/moonshotai/kimi-k2.7-code
Acts as  fix-red[automation]
May      read and push beans
Secrets  none
Memory   refs/automations/fix-red/memory
Limits   30 min, 40 turns, $0.50

[Run the agent] turn 6: git diff origin/sprout...bean/rename-cache
[Run the agent] turn 7: node --test
[Run the agent] turn 8: pushing bean/fix-rename-cache
What it did
Beans pushed   bean/fix-rename-cache
Memory         new at 3f9a1c2 → 8be40d7
Model calls    9 · 41,200 in · 3,100 out
Spend          $0.0515 of $0.50

The pieces

Triggers

Each bean event takes filters, with GitHub's glob rules:

on:
  bean_landed:
    beans: ["*", "!fix-*"]       # bean names
    authors: ["ada"]             # who pushed
    paths: ["src/billing/**"]    # files the landing changed

• beans: and authors: work on the events that name a bean, so not on stalk_moved, stalk_reset or validation_red. paths: works on bean_landed and bean_reverted only, because only those name one commit whose diff is the change. A landing that changes nothing under the paths never starts the automation. Gitstalk reads up to 200 changed files to decide. When it cannot read them (more than 200, or a commit without a parent), the automation starts anyway.
• An automation never fires on its own beans. It runs one at a time: a trigger that arrives while it runs waits, and a newer one replaces it.

Models

Set model: to one of these, or leave it out for the default. Calls go through the gateway and AI Gateway, which charge each call to the run and the repository. Prices are Workers AI list prices in US dollars per million tokens, as read on 9 October 2026.

What a run gets

• A container of its own: each run is one GitHub Actions job on the same Linux container, with git, Node and Python, the repository checked out at the stalk, and the event payload at $GITHUB_EVENT_PATH. It is destroyed when the run ends. Prompt and Shell both run there; see Runners.
• Memory: restored at the start and committed back at the end, up to 50 MiB. Anyone who can read the repository can read it, so never store a secret there. A run whose memory is over the limit does not save it. Set memory: false to turn it off.
• An agent with shell, file and git tools. Its model calls go through Gitstalk, which applies the run's and the repository's spend caps.
• Its own identity, <name>[automation]. With permissions: beans: write it may push bean/*. Those beans go through the pre-land check like anyone's. It can never push to the sprout, the stalk or main.
• Secrets named in secrets:, by the same rule as Actions. Scheduled and manual runs get them. Runs started by a bean event get only the secrets marked available to pre-land checks, because the event carries text anyone with push access wrote. Values are masked in the log.

Limits

A larger timeout-minutes is capped, and the file's report says so. Every number is in Limits and plans.

Not yet planned

• Gitstalk tools for the agent, such as comments and decision cards.
• Your own model keys, and other agents such as Claude Code as a harness.
• Webhooks into an automation.
• A browser editor for .github/workflows files. Automations have one.

Build one in the browser

New automation on the Automations tab opens a form beside the file's YAML. See Automation builder and templates.