GitHub

A GitHub integration makes an agent watch a repository, or every repository of an installation: new issues, pull requests and comments become sessions, and the agent can write back as PR/issue comments. It rides the deployment's AgentConnect GitHub app. AgentConnect Cloud does not require a webhook per repository; an AgentConnect OSS operator configures one deployment-level GitHub App webhook on the Relay.

Watch a repositoryCopy Anchor Link

On the agent: Integrations → Add integration → GitHub.

1. Repository — pick from repositories covered by the GitHub App that the signed-in person may use. Public repositories remain available for read-only setup; private repositories require a linked GitHub identity with access. Picking a repo the agent isn't authorized for opens the authorize step right there. The list starts with each GitHub App installation, as All of <account> (below).

2. Listen for — pull requests, issues, deployments, releases, or any mix; each one gets its own trigger.

3. Trigger when — how eagerly the agent wakes up:

   • opened — when a PR or issue is opened, plus later explicit mentions in that selected family.
   • any update — openings plus supported new revisions, labels, and replies. Closing, reopening, and body edits do not run the agent.
   • @-mention — when the assigned agent or GitHub App is @-mentioned. A native request for the App as PR reviewer is also explicit and can start matching PR reviewers.

   Deployments and releases have no thread to mention in. The agent runs when a deployment is created or on any status it reports, and when a release is published or on any update (every publish, edit or unpublish).

When several agents watch the same repository, Add decision on an issue or pull request row lets a Decision pick which of them take each one.

Watch every repository of an installationCopy Anchor Link

Picking All of <account> watches every repository that installation covers, including repositories added to it later. Each subject you listen for becomes one watch named <account>/*, with its own cadence and review settings.

• It needs the agent's installation authorization, which only an organization owner grants. An owner is taken to that step when it is missing; anyone else can pick the installation once it is authorized.
• Formal reviews and informational Checks need that authorization at Read & write. The repositories do not need their own authorization, even for Checks.
• On one repository, a watch the same agent has for that repository and subject takes precedence, so the agent never runs twice for one event. Use one to give a repository different settings.
• To leave a repository out, remove it from the GitHub App installation, or watch repositories one at a time instead.
• The installation authorization cannot be revoked while the agent still has a watch for the whole installation. Delete those watches first.

Who may trigger an agentCopy Anchor Link

AgentConnect checks the content author's current repository permission through GitHub. Only people with triage, write or admin permission (Maintain counts as write), or on the repository's trusted users list, can start an agent automatically; GitHub's webhook author_association label is not used as authority.

• An issue or pull request opened by someone below that bar does not start an agent, even if its body mentions the agent or GitHub App.
• A current maintainer or trusted user can explicitly mention the agent or App in a comment to request the first turn on an externally authored thread. The same mention from someone below the trigger bar starts no turn: the App answers it once per thread with a fixed note that a maintainer can mention the agent to have it take a look.
• An unmentioned follow-up follows the configured cadence only when both the commenter and the original issue or PR author still pass that bar.
• Native review requests and Check reruns use the same current-maintainer boundary.

AgentConnect checks the author of each comment, including edited content; the webhook sender is not substituted for the content author. Trigger permission is separate from what the agent may do afterward: comments, formal reviews, Checks, and repository writes still require the configured AgentConnect repository grant and GitHub App permissions.

A GitHub identity linked to a signed-in AgentConnect profile can participate in two separate console-user checks:

• optional per-user repository authorization uses it to verify private-repository access and every write grant; and
• Settings → Session access → Require GitHub access uses it when deciding whether the viewer may read a session from a private repository.

Public-repository read-only setup and public-repository sessions do not require a linked GitHub profile. Linking GitHub does not install the GitHub App, grant a repository, or change the webhook-author rules above. See Linked accounts.

Trusted usersCopy Anchor Link

To let someone below that bar start an agent — an outside contributor, or a teammate with read access — add their GitHub username under Trusted users in a pull-request or issue watch's settings (⋯ → Settings…). Editing the list needs edit access to the agent.

• The list belongs to the repository: every watch of that repository, whichever agent or subject, reads the same one. A trusted user passes every check above exactly as a maintainer does — as the commenter, as the author of an issue or pull request, and in unmentioned follow-ups.
• AgentConnect resolves the username to the account's numeric id through the repository's own App credential, and matches that id. A username it cannot resolve is refused as you add it, and a later rename or a reused login vouches for no one else.
• A watch of a whole installation has no list of its own. It reads the list of the repository each event comes from, which only a watch of that repository can edit, so its settings offer none.

What the agent doesCopy Anchor Link

Each qualifying event starts a session on the agent's daemon with the event as context (title, body, diff excerpt as applicable). An enabled watch can post the agent's ordinary final reply even when its workspace is Read only. Formal reviews, status Checks, and repository changes require Read & write authorization. See Workspaces & repositories.

Sessions triggered from GitHub appear in Sessions with the repo/thread as their channel, linked back to GitHub. When repository access sync is enabled, their read-only GitHub members audience follows the source repository's current visibility and the viewer's access rather than an AgentConnect role override.

PR reviewsCopy Anchor Link

For pull-request watches, expand PR review and choose:

• None — run the agent and post its final reply as an ordinary PR comment, without a formal review or Check.
• Brief — allow a formal COMMENT review and inline comments.
• Details — expose controls for inline comments, REQUEST_CHANGES, APPROVE, and an informational status Check.

Formal reviews require agent repository write access and effective GitHub App pull_requests:write permission. Informational Checks additionally require checks:write.

Several agents may watch the same repository. In a PR conversation, @<agent-name> targets one matching agent, while @<github-app-name> broadcasts to every matching reviewer. Both forms still respect event-family, label, installation, live maintainer authorization, and bot-sender safety checks.

When a PR cannot start automatically — most commonly because its author is not a current maintainer — an enabled status Check can offer Request review. A current maintainer can use that action to start the review without adding a comment.

For a complete two-model setup, see Fast PR reviews with deep review on demand.

Require a review before mergingCopy Anchor Link

AgentConnect never blocks a merge itself. To hold merges on a reviewer, require its informational Check in the target branch's ruleset or branch protection:

1. Give the reviewer a pull-request watch with the any update cadence and nothing under Only with labels, and turn on its informational Check under PR review → Details. A Check appears only on revisions the watch reviews, so with any other setting some pull requests wait forever.
2. In GitHub, enable Require status checks to pass and add AgentConnect PR Review: <agent-name>. Set its source to the AgentConnect GitHub App so nothing else can satisfy it.

A merge is then held while the review is queued or running, when the agent requests changes, and when the review fails or never ran. It is not an approval gate:

• A review that ends with comments only reports neutral, which GitHub treats as passing.
• Changing the target branch without a new commit keeps the head's Check, so the earlier result stands until the new review publishes its own.

To recover from a failed or interrupted review, use Re-run on the pull request's Checks tab or the Check's Request review action. A pull request from an author below the trigger bar, and not a trusted user, waits until a maintainer starts the review (Who may trigger an agent).

Make the agent name autocompleteCopy Anchor Link

GitHub's comment box suggests organization teams as you type @, but it has no way to suggest an agent name. Create a team in the organization named exactly after the agent and @<organization>/<agent-name> becomes a suggestion that targets that same one agent:

1. In the organization, Teams → New team.
2. Name it exactly the agent's name — review-bot, not "Review Bot".
3. Leave visibility Visible. A secret team is not offered in the comment box.
4. A description such as "AgentConnect Agent shortcut" tells your teammates what the entry is for.

The team needs no members: AgentConnect matches the text you typed, never the team's membership. Everything else is unchanged — the same event, label, authorization and safety checks apply, and plain @<agent-name> keeps working whether or not the team exists.

AgentConnect never creates, renames or deletes these teams; they are yours to manage. Teams exist only in organizations, so on a repository owned by a personal account only @<agent-name> applies.

Give an agent its own GitHub AppCopy Anchor Link

Every agent starts on the deployment's built-in GitHub App. All agents on it are one actor on GitHub, and GitHub refuses a review from a pull request's own author, so a reviewer cannot approve or request changes on a pull request another agent opened. Give the reviewer its own App to make it a separate actor.

1. On the agent's GitHub card, choose GitHub App. In Edit workspace, the same dialog is under ⋯ → Use its own GitHub App… beside GitHub App connected.
2. Pick a free App of the AgentConnect organization, or choose Create a new GitHub App…. App logos help distinguish the available identities.
3. For a new App, choose its App owner: My personal GitHub account, or Choose from my GitHub organizations to authorize the existing built-in GitHub App and load the accounts it can see. Pick an organization where you can manage GitHub Apps. You can also choose Enter an organization manually… and enter its GitHub organization name.
4. Choose Continue on GitHub. AgentConnect fills in the App's permissions, events and webhook; GitHub checks your permission to create it under the selected owner. Confirm the App and install it on the account and repositories it needs.
5. Back in AgentConnect, the dialog checks that the App reaches everything the agent works on: its workspace repository, authorized repositories and installations, and the repositories it watches. Anything missing is listed with Add on GitHub. Add it there, then Check again.
6. Choose Switch once everything is covered.

The screenshot uses example accounts and App logos. App owner is the GitHub account that owns the registration; it is separate from the accounts where you install the App. New Apps are public by default so you can install them on other accounts later. Public App visibility does not make a repository public or grant repository access: each installation grants access separately. See GitHub App visibility.

From then on the agent works entirely through that App — its events, repository credentials, reviews and Checks — and its GitHub card reads via <app-slug>. @<app-slug> reaches only this agent. A pull request opened by any App of the organization still counts as internal, so agents on different Apps review each other's pull requests automatically.

An App serves one agent at a time. Moving the agent back to the built-in App, or deleting the agent, leaves its App free for another agent.

The organization's Apps are listed under Integrations → Code hosts → GitHub, below the built-in App, each with the agent that uses it. Expand an App to see the accounts it is installed on. An owner can uninstall it from one account there, or delete a free App; a deleted App stays on GitHub until you delete it there too.

If your organization is missingCopy Anchor Link

The account list is limited to organizations visible to the existing built-in GitHub App; it is not a list of every organization you belong to. Linking GitHub in your profile alone does not grant this access, and no separate OAuth App is needed.

• Use Enter an organization manually… when the organization is absent. GitHub still checks your creation permission; manual entry does not grant it.
• To make an installed organization discoverable, the built-in App needs Organization permissions → Members: Read-only, and an organization owner must approve that permission for its existing installation. Self-hosted operators can follow Update an existing GitHub App.
• After approval, choose Refresh GitHub accounts. If the authorization window is blocked, allow popups for the console and try again.

Leaving the Members update unapproved keeps the installation's previous permissions. Existing repository access, PR/Issue operations and webhook delivery continue within those permissions; organization discovery can remain incomplete.

Install the same App on another accountCopy Anchor Link

Open the App's public page on GitHub and choose Install, or visit https://github.com/apps/APP-SLUG/installations/new with your App's slug. Select the additional account and repositories, and complete any required organization-owner approval. Add on GitHub in the coverage check opens this same installation flow.

The settings page for an existing installation manages only that installation's repository access; it does not add another organization. If an older App is private, its owner must first change its visibility to public before other accounts can install it. Return to AgentConnect and choose Check again when completing an App switch.

Manage watchesCopy Anchor Link

The agent page groups its GitHub integration as one card — one row per watched repository, or <account>/* for an installation, with:

• event toggles and the trigger cadence select (Opened / Any update / @-mention; Created / Any status for a deployment, Published / Any update for a release),
• recent deliveries (what fired, when, and the session it started),
• Add repository to watch more repos with the same agent.

RequirementsCopy Anchor Link

• The GitHub App must be installed for your org (Integrations → Code hosts → GitHub → Install on GitHub); the integration dialog offers the install button if it's missing, with an I've installed it — sync refresh.
• An enabled watch can post its ordinary final reply with Read only access. Formal reviews, Checks, and repository changes require Read & write.
• On AgentConnect OSS, the operator must first configure the deployment GitHub App and its Relay webhook.