GitHub logo

GitHub

Run Agents from GitHub Events

Install the GitHub App and agents react to pull requests, pushes, and issues, and answer @ellipsis mentions in any thread. Each session gets a token minted for it, narrowed to the repositories and permissions named in YAML, so nothing in the sandbox can exceed what you granted.

01

Repository events start the work

An agent declares one event surface and the filters that scope it: a pull request opened against your default branch that touches migrations, a push to a release branch, an issue with a given label. Work starts the moment the event fires.

agents/migration-reviewer.yamlone surface per agent
trigger:  type: react  pull_request:    on: [opened, pushed]    repositories: [api-repo]    base: [default]    paths:      - "migrations/**"

One react surface per agent, scoped by filters

02

Mention @ellipsis where the review is happening

Mention @ellipsis in a pull request or issue comment and an agent picks the thread up as its prompt. Replies continue the same conversation with no repeat mention, so a review comment becomes a fix without anyone leaving the pull request.

@ellipsisapi-repo #482
Issue and PR comments
Ask for a change in the thread and the agent picks it up
Pull request reviews
A review body mentioning @ellipsis starts a session
Review comments on a line
The agent gets the file and line as context
No trigger needed: mentions work on every agent you allow them on

Mentions in pull request and issue threads

03

A token per session, scoped in YAML

No agent runs on a developer's credentials. Each sandbox gets its own installation token that lives an hour and dies at teardown, narrowed to the repositories and permission scopes the config names. GitHub mints it with that scope, so the limit holds even against a prompt injection.

agents/migration-reviewer.yamlenforced at the token mint
session:  permissions:    github:      repositories: [api-repo]      permissions:        contents: read        pull_requests: write
GitHub mints the token with this scope, so nothing in the sandbox can exceed it

Narrowed in the config, enforced by GitHub

Frequently asked questions

Works with the tools you already use