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 → Follow 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.

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 (Settings → 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.