Skip to main content
The AgentBees GitHub App replaces the “paste a personal access token” step with a one-click install on GitHub. It’s the recommended way to connect a repo. This page covers what the App can access, how to install and manage it, and how disconnection / uninstall / rotation behave.

​
Why the App instead of a PAT?

Every axis: the App is strictly better.

​
What the App can and cannot access

Requested permissions (only these): Everything else — No access. The App cannot:
  • Read or modify Issues.
  • Read or trigger GitHub Actions workflows.
  • Read Actions secrets, environment secrets, or Dependabot secrets.
  • Modify repo settings, branch protection, or team access.
  • Read deploy keys, webhooks configuration, or repository OAuth apps.
  • Access any repo you did not grant during install.
  • Access any account or org that has not installed the App.

​
Installing

1

Open Connect a repo

Dashboard → Connect a repo.
2

Click Connect with GitHub

You’ll be redirected to github.com/apps/agentbees/installations/new with a signed state parameter that binds the round-trip back to your session.
3

Pick the org or account

You can install on any org you administer, or on your personal account.
4

Grant repos

Pick Only select repositories (recommended) and grant specifically the repos you want AgentBees to work on. Or grant All repositories for one org — including any repos you add in the future.
5

Complete installation on GitHub

Click Install (or Save if updating an existing install).
6

Pick a repo in AgentBees

GitHub redirects you back. AgentBees fetches the list of repos you granted (using the newly-minted installation), you click Pick on one, and the project is created bound to that repo.

​
What happens at task dispatch time

When you start a task on a project connected via the App:
  1. AgentBees signs a 10-minute App JWT (RS256) with the App’s private key held on the server.
  2. It exchanges that JWT for an installation access token scoped to repositories: [owner/name] (the one repo the task is for) with the four permissions above.
  3. That token — TTL ≈ 1 hour — is handed to the ephemeral workspace pod as the git credential.
  4. The token is never persisted on our side. Every dispatch mints a fresh one; nothing is written back to the DB.
This is why a leaked pod token is 1-hour, single-repo damage — not a long-lived key for your whole org.

​
Managing the installation

You can adjust the App from either side. On AgentBees: Connect a repo → Existing connections section → click Disconnect on the AgentBees GitHub App row. This:
  • Revokes the connection on our side immediately (revoked_at set; dispatch stops minting tokens for it).
  • Opens github.com/settings/installations in a new tab so you can also uninstall on GitHub.
On GitHub: github.com/settings/installations → click the AgentBees row. From there you can:
  • Configure — add or remove specific repos from the grant.
  • Suspend — pause the App without uninstalling. Our webhook flips the connection to revoked; unsuspending revives it.
  • Uninstall — remove the App entirely. Our webhook marks every connection under that installation revoked.

​
What happens when you disconnect

Immediately, on the AgentBees side:
  • Any project connected via that installation shows a “This project’s GitHub repo is disconnected” banner.
  • The New task, Merge, and Run pipeline buttons disable (visually greyed out; hover shows an explainer tooltip).
  • API endpoints — task create, send prompt, merge, push, pipeline create — return 409 repo_disconnected. Nothing silently fails in the pod.
  • Existing task history stays fully visible in read-only mode. Cancel, discard, and share still work (they don’t need git).
To resume: install the App again (or unsuspend if you suspended) — the banner clears and everything re-enables.

​
Multi-org installs

You can install the App on more than one GitHub org — each install is a separate row in the Existing connections list, with its own installation ID. Each project is linked to exactly one installation. To connect a repo owned by a different org, just click Connect with GitHub again from Connect a repo — you’ll pick the new org from GitHub’s installer list.

​
Rotation

If you (or we) rotate the App’s private key, existing installations continue to work — the key material lives on our server and rotates independently of what’s stored on GitHub or on your side. There is no action required on your end for a rotation.

​
Enterprise / self-hosted GitHub

If you’re on an isolated tenant with a self-hosted GitHub Enterprise Server, the App can be registered against your GHES instance instead of github.com. See the enterprise-tenant runbook for the GITHUB_APP_BASE_URL override. Enterprise customers may also register their own App under their own GitHub org and hand us the App ID + private key — that model gives your security team full control over the key material, and lets you revoke AgentBees at any time by uninstalling on GitHub. See the same runbook under “Custody models”.

​
FAQ

Q: Can AgentBees access repos I did not grant? No. The App can only touch repositories that appear in the granted list for one of its installations. Repos in other orgs, or repos in your org that you didn’t tick, are invisible. Q: What if I install the App but never use it? Nothing happens. The App does not clone, poll, or notify — it just holds the installation. A task must be dispatched by you (or your teammate) to mint a token. Q: Can teammates use the same installation? Yes. The installation is org-level; any AgentBees user in the same workspace as you (any org member with the right role) can dispatch tasks that use it. Q: How do I know if the webhook is working? On GitHub, the App’s settings page has an Advanced → Recent Deliveries tab. Every install/uninstall/suspend event should show a 200 response from our webhook. If they’re red, uninstalls won’t be reflected in AgentBees automatically — but the Disconnect button on our side still works. Q: What about the “Show manual entry” toggle? It’s for automation. If you have a script that already knows an installation ID and just wants to record it in AgentBees, you can paste it directly instead of clicking through GitHub. Almost no one needs this — the Connect with GitHub button is the normal path.