Surfaces
GitHub
The GitHub surface lets people mention your GitHub App in an issue or pull request conversation and get the agent's answer there as a comment.
Each issue or pull request is one conversation with the agent, keyed by repository and number (owner/repo#42). A mention becomes an ordinary run with the agent's model, tools, and limits. Answers come from the app itself, as <app-slug>[bot].
Add GitHub to an agent
Only owners and admins can add a surface. Go to Agents, open the agent, then Settings → Where it answers → Add surface → GitHub, and choose Set up with the agent to be guided through it.
Let Adapt create the app
Choose one:
- Organization app: for your team's repositories, owned by the organization. Enter the organization's name as it appears in
github.com/your-org; you need permission to create apps there. - Personal app: for your own repositories, owned by you.
Continue on GitHub opens GitHub with the app already described. Approve it there, and Adapt saves the App ID, private key, and webhook secret for you. Then install the app on the repositories it should answer in.
The app Adapt creates is private to its owner's account, sends its webhook to this connection, and subscribes to Issue comment. It asks for these repository permissions:
- Read and write: Contents, Issues, Pull requests, Checks, Actions, Workflows.
- Read-only: Commit statuses, Deployments.
Connect an app you already have
Paste three values into the connection:
- App ID: in the app's settings, under About.
- Private key: generate one under Private keys and paste the
.pemfile's contents. - Webhook secret: choose a long random value and use the same one in the app's webhook settings.
Then, in the app's settings, turn on Webhook and set its URL to the connection's Request URL, <your Adapt URL>/api/surfaces/<connection ID>. Under Permissions & events, grant the permissions listed above and subscribe to Issue comment. Existing installations must approve new permissions. Install the app on the repositories it should answer in.
The Request URL must be a public HTTPS address; see Self-host.
Check the connection
Open the agent's GitHub row under Where it answers to see its Setup check. Using the app's own credentials, Adapt checks:
- the App ID and private key, and which
[bot]name replies will come from; - the app's permissions, listing any that are missing;
- its installations and how many repositories each can reach;
- its webhook: on, pointing at this connection, sending JSON, and its last delivery.
If the webhook check needs a delivery, redeliver the app's ping under Advanced → Recent Deliveries in GitHub. A connection that's on is permitted to run, not verified healthy.
Mention the app
Write @<app-slug> in a new comment on an issue or pull request in a repository where the app is installed. The rest of the comment is the request. Quoted text is ignored, so quoting an earlier mention doesn't start a run.
Adapt ignores:
- comments that don't mention the app, and the app's own events;
- comments posted more than a day ago or dated more than 5 minutes ahead, so a replayed delivery can't start a run;
- comments where the comment's author isn't the webhook's sender.
A mention in a pull request review comment gets its answer in that review thread.
Who the agent answers
Each GitHub surface comes with an automation, Respond to trusted member mentions, on the agent's Automations tab. By default it runs only for a sender Adapt recognizes as a workspace member who is also an owner, member, or collaborator on the repository.
Two options on the automation's event widen who can start a run:
- Allow responses to non-workspace members: off by default. When on, a mention runs anonymously: no Adapt user and no workspace role. With this on, Adapt doesn't also require the sender to be a repository collaborator, so on a public repository anyone who can comment can start a run.
- Allow responses to bots: off by default. Other bots then run anonymously. The app's own events are always ignored.
History search and Adapt administration tools are never available in GitHub threads.
What the agent can do in GitHub
In a GitHub conversation the agent gets tools for that repository:
- Read:
github_list_files,github_read_file,github_pull_request,github_list_issues, plussurface_contextto read the conversation. - Change:
github_create_branch,github_commit_files,github_create_pull_request,github_update_pull_request,github_merge_pull_request,github_create_issue,github_update_issue,github_comment. github_apicalls any GitHub REST endpoint the app's installations allow, for what the other tools don't cover.surface_updateedits only replies the app posted in this conversation.
When the agent has a sandbox, commands in it get HTTPS Git authentication for the app's installed repositories, so it can clone and push. The credentials are scoped to that command and redacted from its output.
In the agent's other conversations, such as web chats, the GitHub tools take a repository argument limited to the app's installations.
Every tool call runs as soon as the model makes it, and everything the app posts is visible to people who can read the repository. Keep that in mind before asking for sensitive work in a public repository.
Replies
While a run works, the app adds an eyes reaction to the issue or pull request, and removes it once the answer is delivered. The final answer is posted as a comment from the app; a failed or interrupted run posts a short error instead. Answers longer than about 60,000 characters are cut to GitHub's comment limit, with a note saying so.
GitHub attachments aren't reachable with the app's token, so the agent doesn't receive files attached to comments.
If GitHub fails after Adapt has started posting, the delivery is marked uncertain and is never sent again, so a comment is never posted twice. Check the conversation on GitHub before asking again.
Review pull requests
The agent's Review pull requests automation is off by default. Turned on, it runs when a pull request is opened or marked ready for review. To receive those events, subscribe the app to Pull request in its GitHub settings; apps Adapt creates subscribe only to Issue comment. The same sender options apply as for mentions.
The agent reads the exact base and head commits, starts an Adapt Review check on the head, and then publishes a formal COMMENT review pinned to the commit it reviewed. The review has a summary, the important files, and its findings, inline where a diff line is known. The check records a confidence score out of 5: 3 to 5 passes, 0 to 2 fails.
The review replaces the usual answer comment. It never approves, requests changes, or blocks a merge. If the pull request changes before the review is published, the agent must review the new commits. Edit the automation's prompt to change what the review looks for.
Read GitHub threads in Adapt
Any member who can view the agent can open a GitHub conversation in Adapt, read-only, with each message labeled by its author or as anonymous. To continue it, comment on GitHub. The thread's owner and admins can rename or delete it; the next mention on that issue or pull request then starts a fresh conversation.