Start sessions automatically

An automation starts a session when something happens, so you don’t have to. It might be a morning digest on a schedule, a support request in a Slack channel, or a failing build on your main branch. Each session the automation starts works like any other session. It runs the way How it runs sets it, asks when it needs you, and opens a pull request.

Open Automations from the sidebar to see yours or your group’s, and to make a new one. Owners and Admins also see Everyone.

What can start an automation

Some kinds need an integration first. GitHub issues and CI checks need the GitHub App, which Connect your code covers. For the others, see Slack, Atlassian, Sentry, and Datadog. Jira, Sentry, and Datadog send their events through a connection that an Owner or Admin sets up once for the workspace. They find its webhook URLs and secrets on the Triggers tab of the Automations page.

Describe it, or build it

The quickest way is to describe what you want. On the Automations page, type it in the Describe an automation box and choose Set it up. For example:

Every weekday at 9:00, summarize yesterday's merged PRs and post the digest in #eng-updates

The agent sets up the automation from your description and asks about anything it can’t work out. The Examples tab has more prompts to start from. Each one opens a new session with the prompt filled in.

To build it yourself, choose New automation and fill in the form. The sections run in the order an event travels.

What it tells the agent

What to do is the task each session is given. You can drop values from the event into it by writing a token in double braces. Insert from the event lists the ones the kind offers. These work on every kind except a schedule, and a Slack message has no {{ payload }}:

Each kind adds its own, such as the repository and labels for a GitHub issue or the check name and branch for a CI check. A schedule has no event, so Insert from the schedule offers its time, date, and timezone instead. The form shows what’s available and previews the finished prompt as you type.

Under the prompt, you also choose how each session runs.

• How it runs is the session’s autonomy. See Autonomy.
• Which models each session starts on is Owner’s default, Org’s picks, or Pick a model. When you pick one, you can set how deeply it thinks and a model per phase, and you can only pick models that everyone the automation may run as can use. See Choose a model and how hard it thinks.
• How far the shepherd takes each session’s PR is Project’s default, Ask before every fix, Ask before merging, or Auto merge when green. See Pull requests.
• Plugins adds plugins to each session on top of its owner’s own, if the owner is allowed to use them.
• Where the session talks chooses where in Slack the session posts its updates.

Which project and repository

An automation can route to no project, one project, or several.

• No project. Each session starts outside a project. You can name one repository for it.
• One project. Each session starts in that project and uses its repositories and defaults.
• Several projects. Evergreen picks the project each event fits best, using the What belongs here hint you give each one. It uses the first project when it’s unsure.

GitHub issue and CI check automations listen on the repositories their projects link to, so they need at least one project. A schedule can start sessions in one project at most.

Who the sessions run as

Under Who owns each session, you choose whose name and Claude allowance each session uses. Evergreen skips anyone who has no Evergreen account, no access to the project, or no allowance, and falls back to whoever set up the automation.

Each person who takes turns is asked to accept first, and Evergreen skips them until they do, unless they own the automation or its projects. You can also list people under Joins every session. They join each session as collaborators, but they don’t own it or pay for it. Turn on Make private so only the people you add can find the sessions it starts.

Limits

• At most, per hour. The most sessions the automation can start in an hour. The default is 5, and the highest you can set is 60.
• At most, per day. The most sessions it can start in 24 hours. The default is 20, and the highest you can set is 200.

Events over a limit wait and start as the limit frees. An event that waits 24 hours is dropped. To drop events over the limit straight away instead, turn on Skip events that arrive while the limit is reached. The automation’s page shows how many events are waiting or dropped, and whoever can edit it can choose Discard waiting or Replay dropped.

Three more controls keep an automation from doing too much.

• Batch events holds events and releases them together, as One session for the batch or A session for each event. You release a batch after a number of minutes, once a number of events are waiting, or whichever comes first.
• Send follow-ups to the session already on the same issue sends a later event about the same issue to the session already working on it, instead of starting another.
• Until describes what done looks like. Each session checks it before and after its task, and the automation pauses once the goal is met. Without it, the automation runs until someone pauses it.

If an automation’s sessions keep setting it off again, Evergreen pauses it and says so on its page. Check what the sessions wrote, then choose Resume.

Set up a webhook

A webhook automation gives you a Hook URL and a Secret when you create it. Copy the secret then, because Evergreen shows it once. If you lose it, choose Rotate secret on the automation’s page, and the old one stops working at once.

Your sender posts a JSON object to the hook URL and proves it holds the secret in one of two ways.

• Send X-Evergreen-Signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with the secret>.
• Or send Authorization: Bearer <secret>.

Here’s a signed request. It sets X-Evergreen-Delivery so a retry counts as the same event.

BODY='{"title":"Disk full on db-1","url":"https://pager.example/1"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
curl -X POST "$HOOK_URL" -H "Content-Type: application/json" \
  -H "X-Evergreen-Signature: sha256=$SIG" -H "X-Evergreen-Delivery: evt-1" -d "$BODY"

Evergreen reads {{ title }} from the first of title, summary, subject, name, or event that the body has. It reads {{ body }} from body, description, text, or message, and {{ url }} from url, html_url, or link. {{ payload }} is the whole body. A bad signature gets a 403. A paused automation answers 202 and starts nothing, so the sender doesn’t retry.

Check what happened

Each automation has a page with a Recent firings list. It shows each event it received, newest first, and what happened to it.

The page also shows a health badge. It reads Receiving events when all is well, No event received yet before the first one arrives, Not wired up when the source isn’t sending, Prompt cut when the prompt reads more of an event than Evergreen keeps, and Missing tools when the prompt names an integration that someone who will own the sessions hasn’t connected. With Missing tools the automation still runs, but those sessions run without that integration. Ignore it if the prompt uses that name for something else.

Pause stops an automation without deleting it. Run now on a schedule starts one session right away, and Fire on an issue runs an existing GitHub issue through a GitHub issue automation. History shows who changed the automation, and when.

Share lists the automation’s collaborators, who can change anything about it but can’t delete it. Anyone but the owner can choose Copy to my automations. The copy is yours and starts paused. If the owner leaves the organization, an admin, the owner’s manager, or a collaborator can choose Take over.