Triggers

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

YAML

trigger:

type: cron

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:

YAML

trigger:

type: cron

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

YAML

trigger:

type: react

pull_request:

on: [pushed]

repositories: [api-repo]

base: [main]

draft: false

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.

Event	When it fires
`opened`	Opened, reopened, or marked ready for review
`pushed`	New commits, including when the pull request opens
`merged`	Merged
`closed`	Closed without merging
`review_submitted`	A review is submitted
`commented`	A comment is added

Branch pushes

YAML

trigger:

type: react

push:

repositories: [api-repo]

branch: [default, 'release/*']

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

YAML

trigger:

type: react

issue:

on: [opened]

repositories: [api-repo]

labels: [bug]

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

CI checks

YAML

trigger:

type: react

check_run:

on: [failed, timed_out]

repositories: [api-repo]

names: ['test *', lint]

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.

Value	When it fires
`requested`, `queued`, `waiting`, `pending`	The check is created in that state
`started`	The check is created already running
`passed`	The check concludes `success`
`failed`	The check concludes `failure`
`timed_out`, `cancelled`, `skipped`, `neutral`, `action_required`, `stale`	The 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

YAML

trigger:

type: react

check_suite:

on: [failed]

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

YAML

trigger:

type: react

workflow_run:

on: [failed]

names: [CI]

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

YAML

trigger:

type: react

status:

on: [failed, errored]

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

YAML

trigger:

type: react

release:

on: [published]

repositories: [api-repo]

tag: ['v*']

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

YAML

trigger:

type: react

pull_request:

on: [opened]

repositories:

include: [api-repo, web-repo]

exclude: [archived-repo]

for:

users: true

bots: false

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

YAML

trigger:

type: react

linear_issue:

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

YAML

trigger:

type: react

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

YAML

trigger:

type: react

sentry:

on: [issue_alert]

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

YAML

trigger:

type: react

enabled: false

linear_issue:

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