Install the GitHub App and agents react to pull requests, pushes, and issues, answer @ellipsis mentions in any thread, and work with a token scoped to the repositories and permissions you named. Nothing in the sandbox can exceed what you granted.
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, while the context is fresh.
trigger: type: react pull_request: on: [opened, pushed] repositories: [splitshift-api] base: [default] paths: - "migrations/**"One react surface per agent, scoped by filters
Pull requests, pushes, and issues, each with its own action list. The pushed action covers the open and every later commit, so a reviewer agent stays current on a long-running branch without firing twice on the same commit.
The whole GitHub trigger vocabulary
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.
permissions: github: repositories: [splitshift-api] permissions: contents: read pull_requests: writeNarrowed in the config, enforced by GitHub
Mention @ellipsis in a comment, a review, or on a specific line 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.
Mentions on comments, reviews, and single lines
One install covers config sync, every trigger, the per-session credential, and everything an agent posts back.
Install the GitHub App on an account or organization and pick the repositories. Agents only ever see the repositories you granted.
Agent YAML lives in your repository. The version on your default branch is the live agent, so deploying is merging.
React to opened, pushed, merged, closed, review_submitted, and commented, filtered by base branch, labels, changed paths, or author.
React to a push on its own, scoped by branch pattern or the changed files in the pushed range.
React to opened, closed, and commented, filtered by label or the account that acted.
@ellipsis in an issue comment, a review body, or a review comment on a line starts or continues a conversation there.
Each sandbox gets its own installation token, minted when the sandbox starts. It lives an hour and dies with the sandbox. No developer's personal credential is involved.
read_only, or an explicit map of GitHub permission scopes, plus a list of repositories. It can only reduce what the installation granted.
The token is minted with the reduced scope, so nothing in the sandbox, including a prompt injection, can exceed it.
The agent works the way your engineers do: real git, the gh CLI, and a set of GitHub tools resolved against what you granted.
Agents open pull requests, edit descriptions, and comment through the installation, always as the Ellipsis bot.
With code review enabled, Ellipsis posts one comment-only review per push, anchored to the commit it reviewed. It never approves or pushes commits.
Install the Ellipsis GitHub App from app.ellipsis.dev/install. GitHub asks which account or organization to install on and which repositories to grant, either all of them or a selected list. If you are not an organization admin the same flow files a request for your admin to approve. That is the whole setup.
Three surfaces. pull_request reacts to opened, pushed, merged, closed, review_submitted, and commented. push reacts to the push itself. issue reacts to opened, closed, and commented. An agent declares exactly one surface, and each carries its own filters: repositories, base and head branch, draft state, labels, and changed-path globs.
Exactly what the config grants. By default the session token carries the installation's permissions on the installation's repositories. The permissions.github block narrows it: read_only for read access to contents, issues, metadata, and pull requests, or an explicit map like {contents: read, pull_requests: write}, plus a repositories list. GitHub mints the token with that reduced scope, so the restriction is enforced by GitHub rather than by Ellipsis.
Never. Every sandbox gets its own installation token, minted from your GitHub App installation when the sandbox starts, with a one-hour lifetime, revoked at teardown. That is what git, gh, and the agent's GitHub tools authenticate with.
Mention @ellipsis in an issue comment, in a pull request review body, or in a review comment on a specific line, and a session starts with that thread as its context. A review comment on a line hands the agent the file and line too. Replies continue the same durable conversation, and an agent with a mention trigger can replace the built-in responder with your own prompt, repositories, and budget.
No. Code review posts comment-only reviews: it never approves, never requests changes, and never pushes commits to your branch. Agents can open pull requests and comment, always as the Ellipsis bot, and branch protection applies to the agent exactly as it does to a developer.