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.

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.

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

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
  • Every matching agent runs

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 don't count. The session receives the issue. Name the repositories it needs in session.environment.

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.

Mentions

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

On this page

SchedulesPull requestsBranch pushesIssuesRepositories and authorsLinear issuesSlack channelsSentry alertsMentions
Schedule a demo