Triggers

Run agents on schedules or matching events.

An agent has at most one trigger. Without one, it runs only when you start it from the dashboard or API. Each run starts a new session that stays open for follow-ups unless the agent sets conversation.interactive to false. For event triggers, the session's first message includes the event.

Schedules

1
trigger:
2
type: cron
3
schedule: '0 9 * * 1-5'

Runs at 09:00 UTC on weekdays. schedule is a 5-field cron expression (minute, hour, day of month, month, day of week) in UTC:

1
trigger:
2
type: cron
3
schedule: '0 */6 * * *'

Runs every 6 hours, at 00:00, 06:00, 12:00, and 18:00 UTC. If Ellipsis is unavailable when a run is due, that run is skipped and the next one starts on schedule.

Schedules in the dashboard lists every agent with a schedule and when each runs next. A schedule's page lists its next runs and the sessions it started. el agent list shows the next run, and the API returns it as next_run_at on the agent (GET /v1/agents/{id}).

Pull requests

1
trigger:
2
type: react
3
pull_request:
4
on: [pushed]
5
repositories: [api-repo]
6
base: [main]
7
draft: false
8
paths: ['src/**', 'tests/**']

Runs on each push to a non-draft pull request into main that changes a matching path, including when the pull request opens.

EventWhen it fires
openedOpened, reopened, or marked ready for review
pushedNew commits, including when the pull request opens
mergedMerged
closedClosed without merging
review_submittedA review is submitted
commentedA comment is added

Branch pushes

1
trigger:
2
type: react
3
push:
4
repositories: [api-repo]
5
branch: [default, 'release/*']
6
paths: [package.json, package-lock.json]

Runs when a push to the default branch or a release/ branch changes package.json or the lockfile. Push triggers have no on field.

Issues

1
trigger:
2
type: react
3
issue:
4
on: [opened]
5
repositories: [api-repo]
6
labels: [bug]

Runs when someone opens an issue labeled bug in api-repo.

CI checks

1
trigger:
2
type: react
3
check_run:
4
on: [failed, timed_out]
5
repositories: [api-repo]
6
names: ['test *', lint]
7
branch: [default, 'release/*']

Runs when a check named lint or starting with test fails or times out on the default branch or a release/ branch of api-repo. A check is a GitHub Actions job or a check another CI app reports.

ValueWhen it fires
requested, queued, waiting, pendingThe check is created in that state
startedThe check is created already running
passedThe check concludes success
failedThe check concludes failure
timed_out, cancelled, skipped, neutral, action_required, staleThe check concludes with that value
  • names matches check names exactly or by a prefix ending in *. Omit it to match every check
  • branch is the branch the check ran on. A check on a fork's pull request has none
  • for is the author of the commit the check ran on, so an agent's own commits don't count unless bots includes it
  • Every matching check starts its own session, so a matrix of 20 failing jobs starts 20 sessions per agent. To run once when a whole workflow fails, use workflow runs
  • A check on a commit that is no longer the head of its pull request starts nothing, so an agent never works on code that was already replaced

The session receives the check, its output, and the file annotations GitHub holds for it, plus the pull request it belongs to. For a GitHub Actions check it names the workflow run, so the session can read the job's log with gh.

The Ellipsis GitHub App needs the Checks permission on your installation. GitHub prompts the installation's owner to accept it, and until then Ellipsis receives no check events.

Check suites

1
trigger:
2
type: react
3
check_suite:
4
on: [failed]
5
apps: [buildkite]

Runs once when every check Buildkite reported on a commit has finished and the suite failed. GitHub reports a suite only when it finishes, so on takes the finished values from CI checks and startup_failure. apps matches the reporting app's slug, such as github-actions. branch, for, and the skip for a commit that is no longer the head of its pull request work as they do for checks. Needs the Checks permission.

Workflow runs

1
trigger:
2
type: react
3
workflow_run:
4
on: [failed]
5
names: [CI]
6
branch: [default]

Runs when the CI workflow fails on the default branch. on takes every CI checks value and startup_failure. queued fires when a run is queued, started when it starts, and action_required when it waits for approval. names matches workflow names exactly or by a prefix ending in *. branch, for, and the skip for a commit that is no longer the head of its pull request work as they do for checks. The session can read the run's log with gh. Needs the Actions permission.

Commit statuses

1
trigger:
2
type: react
3
status:
4
on: [failed, errored]
5
names: ['ci/circleci*']

Runs when a CircleCI status fails or errors. Some CI tools post commit statuses instead of checks. on takes pending, passed, failed, and errored. names matches the status context, its name on the pull request. branch matches when any branch GitHub lists for the commit matches. for and the skip for a commit that is no longer the head of its pull request work as they do for checks. Needs the Commit statuses permission.

Releases

1
trigger:
2
type: react
3
release:
4
on: [published]
5
repositories: [api-repo]
6
tag: ['v*']
7
prerelease: false

Runs when a release whose tag starts with v is published in api-repo, skipping prereleases. A draft fires when it is published, not when it is saved; edits, deletions, and unpublishes never fire.

  • tag matches tag names exactly or by a prefix ending in *; omit it to match every tag
  • prerelease: true matches only prereleases and false only full releases; omit it to match both
  • for is the release's author, so a release cut by CI or a release bot needs bots to include it

The session receives the release's tag, name, notes, target, author, and URL, and can read the release and the ones before it with gh.

Repositories and authors

1
trigger:
2
type: react
3
pull_request:
4
on: [opened]
5
repositories:
6
include: [api-repo, web-repo]
7
exclude: [archived-repo]
8
for:
9
users: true
10
bots: false
11
teams: [platform]

Filters only decide which events match. They don't grant access or choose which repositories the session checks out; the environment does.

  • An empty repository list matches every installed repository
  • Branch filters accept exact names, prefixes ending in *, and default
  • Labels match when any listed label is present
  • Paths are globs of files to match; ! patterns aren't allowed
  • teams lists GitHub team slugs of the installed organization, platform for @org/platform; the author must pass users and be on one of the teams, and bots never are
  • Every matching agent runs

A team named in teams must exist when the file syncs; a missing team is a sync error, and a personal account installation can't use teams. Membership is checked against GitHub each time an event matches, and members of child teams count.

Linear issues

1
trigger:
2
type: react
3
linear_issue:
4
on: [opened]

Runs when a person creates a Linear issue. Issues created by bots never count. The session receives the issue and, for a change, the values before and after it. Name the repositories it needs in session.environment.

EventWhen it fires
openedAn issue is created
updatedEvery field listed in changed changes in one edit

updated needs changed, which names the fields to watch. Each field takes from and to, the values before and after the change. Leave out from to match a change from any value, and to to match a change to any value. labels takes added and removed instead, because an issue holds several labels. state takes status names such as In Review or status types such as started, assignee takes member emails or none, priority takes none, urgent, high, medium, or low, and project takes project names or none. The fields list every option.

The same names work as filters on the issue as it is after the event, alongside team, which takes team keys such as WEB. assignee as a filter also takes any.

1
trigger:
2
type: react
3
linear_issue:
4
on: [updated]
5
changed:
6
state:
7
from: [In Review]
8
to: {exclude: [completed, canceled]}

Runs when a reviewer moves an issue out of In Review to any status that isn't finished, so the agent can read the review comments and fix its pull request.

1
trigger:
2
type: react
3
linear_issue:
4
on: [updated]
5
changed:
6
labels:
7
added: [agent]

Runs when someone adds the agent label to an issue, so a person hands work to the agent with one label.

1
trigger:
2
type: react
3
linear_issue:
4
on: [updated]
5
team: [WEB]
6
assignee: none
7
changed:
8
state:
9
to: [Ready for Agent]

Runs when an unassigned WEB issue moves into the Ready for Agent column from any status.

1
trigger:
2
type: react
3
linear_issue:
4
on: [updated]
5
project: [Checkout]
6
changed:
7
priority:
8
to: [urgent]
9
for:
10
users: true
11
bots: true

Runs when a person or an integration, such as an incident tool, raises a Checkout issue to urgent, so the agent starts investigating before anyone picks it up.

1
trigger:
2
type: react
3
linear_issue:
4
on: [opened]
5
team: [SUP]
6
labels: [bug]
7
project: {exclude: [Internal Tools]}

Runs when someone files a SUP issue labeled bug outside the Internal Tools project, so the agent tries to reproduce customer bugs as they arrive.

  • Each filter takes one value, a list, or include and exclude lists, and matches when any listed value matches
  • Every filter and every field in changed must match
  • Status, label, and project names match exactly, and a name your Linear workspace doesn't have is a sync error
  • for is the person who changed the issue, so a change by an integration such as GitHub counts only when bots includes it
  • A change Ellipsis makes never starts a session, so an agent can't trigger itself
  • Every matching issue starts its own session, so moving 50 issues at once starts 50 sessions per agent

Slack channels

1
trigger:
2
type: react
3
slack_channel: {}

Runs when someone creates a Slack channel. The session receives the channel's name and purpose. To answer messages instead, use Slack mentions.

Sentry alerts

1
trigger:
2
type: react
3
sentry:
4
on: [issue_alert]
5
projects: [api]

Runs when an issue alert fires in the api Sentry project. on accepts issue_alert and metric_alert; omit projects to match every project. A sentry.yaml file, when present, replaces these triggers.

Pause a trigger

1
trigger:
2
type: react
3
enabled: false
4
linear_issue:
5
on: [opened]

Pauses the trigger and keeps its definition in the file: new Linear issues no longer start sessions, and nothing else changes. Starts from the dashboard, CLI, and API still work, and open sessions keep taking follow-ups. The dashboard shows the agent as Trigger paused. Set enabled back to true, or remove the line, to resume. A paused cron resumes at its next scheduled time and doesn't make up the runs it missed. To pause the whole agent, including starts, set ellipsis.enabled: false.

Mentions

@ellipsis mentions are configured separately, in GitHub, Slack, and Linear handler files.

On this page

SchedulesPull requestsBranch pushesIssuesCI checksCheck suitesWorkflow runsCommit statusesReleasesRepositories and authorsLinear issuesSlack channelsSentry alertsPause a triggerMentions
Schedule a demo