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.

CI checks

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

Runs when a check named lint or starting with test fails on the default branch or a release/ branch of api-repo. A check is a GitHub Actions job or a status another CI app reports; failed covers the failure and timed_out conclusions. A cancelled, skipped, or neutral check never fires.

  • 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 commit's author, or the pull request's when the check is attached to one, so an agent's own commits don't count unless bots includes it
  • Several checks failing on one commit start one session per agent, not one per check

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 failing 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; until then, Ellipsis receives no check events.

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 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 pushesIssuesCI checksReleasesRepositories and authorsLinear issuesSlack channelsSentry alertsMentions
Schedule a demo