> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentbees.ai/llms.txt > Use this file to discover all available pages before exploring further. # The AgentBees GitHub App > How the GitHub App works, what it can and cannot access, and how to install, manage, disconnect, and rotate. 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? | | PAT | AgentBees GitHub App | | ---------------------------------- | ------------------------------------------ | ------------------------------------------------------ | | Secret you paste | Yes — a PAT you create | **None** | | Secret we store per repo | Long-lived encrypted PAT | **Installation ID only** — no secret | | Token lifetime in a pod | Long-lived | **\~1 hour**, auto-expiring | | Scope of a pod token | Whatever the PAT granted (often too broad) | **Exactly one repo** + 4 specific permissions | | Revocation | Rotate/delete the PAT | **Uninstall the App** or click Disconnect — one action | | Whose access it uses | The PAT owner's | **The installer's** own GitHub permissions | | Blast radius of a leaked pod token | Long-lived, potentially broad | **1 hour, single repo, four permissions** | Every axis: the App is strictly better. ## What the App can and cannot access **Requested permissions (only these):** | Repository permission | Access | | --------------------- | ------------------- | | Contents | Read & write | | Pull requests | Read & write | | Commit statuses | Read & write | | Metadata | Read (auto-granted) | **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 Dashboard → Connect a repo. 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. You can install on any org you administer, or on your personal account. 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. Click Install (or Save if updating an existing install). 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](/enterprise/dedicated-cluster) 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.