---
title: GitHub
description: Reach your agent from GitHub issue, pull request, and review comments, and from CI events, with the repository checked out in the sandbox.
url: "https://eve.dev/docs/channels/github"
docs_index: /llms.txt
type: integration
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

A GitHub agent works directly on a repository. Write its invocation token, such as `@my-agent`, in a new issue, pull request, or review comment, and the agent answers in that thread. On a pull request it already has the diff in context, and every turn checks out the repository into the sandbox. It can also wake on its own when an issue opens or CI fails. [Set up](#set-up) creates the GitHub App through Vercel Connect.

For information on all configuration and customization options, see the [GitHub reference](/docs/channels/github/reference).

## Set up

#### Vercel Connect

Run the guided setup from your agent project, then deploy:

```bash
eve add channel/github
eve deploy
```

Setup signs you in to Vercel, links a project, creates a GitHub App through Vercel Connect, routes its webhooks to `/eve/v1/github`, and writes the channel file:

```ts title="agent/channels/github.ts"
import { connectGitHubCredentials } from "@vercel/connect/eve";
import { githubChannel } from "eve/channels/github";

export default githubChannel({
  botName: "my-agent",
  credentials: connectGitHubCredentials("github/my-agent"),
});
```

After deploying, open the GitHub App in the Connect dashboard and install it on the organization or account you want the agent to work in.

#### Self-managed

Create a GitHub App and set its credentials. The channel reads them by default:

```bash
GITHUB_APP_ID=...
GITHUB_APP_PRIVATE_KEY=...   # PEM
GITHUB_WEBHOOK_SECRET=...
```

```ts title="agent/channels/github.ts"
import { githubChannel } from "eve/channels/github";

export default githubChannel({
  botName: "my-agent",
});
```

Point the App's webhook URL at `https://your-agent.example/eve/v1/github`, subscribe to `issue_comment` and `pull_request_review_comment`, and install the App on your repositories. Your own GitHub App also works on Vercel. See [Bring your own GitHub App](/docs/channels/github/reference#bring-your-own-github-app) for the other events and lazy credentials.

## Default channel behavior

By default, a new comment that includes `@my-agent` starts a turn. The token is plain text, not a GitHub mention, so GitHub may not autocomplete or link it. The agent reacts with 👀 when it starts, then replies on the issue or PR timeline, or in the review thread. Each later comment in that thread that includes `@my-agent` continues the same session.

- To customize which comments start a turn, override `onComment`. See [Dispatch](/docs/channels/github/reference#dispatch).
- To also wake on new issues, pull requests, or CI, see [Trigger on issues, pull requests, and CI](#trigger-on-issues-pull-requests-and-ci).
- To turn off the reaction or change how replies are posted, see [Delivery](/docs/channels/github/reference#delivery).

## Trigger on issues, pull requests, and CI

Issue, pull request, and CI hooks are off by default. Each hook returns `{ auth }` to start a turn, or `null` to ignore the event. This channel triages new issues and failed GitHub Actions check suites on pull requests:

```ts title="agent/channels/github.ts"
import { defaultGitHubAuth, githubChannel } from "eve/channels/github";

export default githubChannel({
  botName: "my-agent",
  onIssue: (ctx, issue) => (issue.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null),
  onCheckSuite: (ctx, suite) =>
    suite.action === "completed" &&
    suite.conclusion === "failure" &&
    suite.app.slug === "github-actions" &&
    suite.pullRequests.length > 0
      ? {
          auth: defaultGitHubAuth(ctx),
          context: [`Triage failed check suite ${suite.checkSuiteId} at ${suite.headSha}.`],
        }
      : null,
});
```

Subscribe the GitHub App to each event you handle, such as `issues` or `check_suite`. A CI turn replies on the first pull request in `pullRequests`, so return `null` when the list is empty.

## Access the repository

Before the first model call, each turn checks out the relevant ref into the sandbox, so file and shell tools run against the real tree. The installation token never enters the sandbox; GitHub auth is added at the network firewall, which needs a firewall-capable sandbox such as Vercel's. On a pull request, the PR metadata and changed-file patch are already in the agent's context.

For any GitHub API the channel doesn't wrap, call `ctx.github.request({ method, path, body })` with the installation token.

## Human-in-the-loop interactions

By default, approvals and questions post as a comment prompt, since GitHub comments have no buttons. The person's reply comment answers the pending request.

- To require approval for a tool or ask the person a question, see [Human-in-the-loop](/docs/human-in-the-loop).
- To customize the prompt, override `events["interaction.opened"]`. See [Human-in-the-loop](/docs/channels/github/reference#human-in-the-loop-hitl).

## Start conversations proactively

Send to the GitHub channel from a [schedule](/docs/schedules#handler-form-run) or [another channel](/docs/channels/custom#cross-channel-hand-off). The target needs `owner`, `repo`, and either `issueNumber` or `pullRequestNumber`:

```ts title="agent/schedules/weekly-triage.ts"
import { defineSchedule } from "eve/schedules";
import github from "../channels/github";

export default defineSchedule({
  cron: "0 14 * * 1",
  async run({ to, waitUntil, appAuth }) {
    waitUntil(
      to(github, { owner: "acme", repo: "web", issueNumber: 42 }).send(
        "Post this week's triage summary.",
        { auth: appAuth },
      ),
    );
  },
});
```

## Reference

The [GitHub reference](/docs/channels/github/reference) covers options, credentials, every inbound hook, CI event fields, delivery, PR context, sandbox checkout, and proactive sessions.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)