--- seo_title: GitHub Connector seo_description: Two separate GitHub setups: repository tools for agents, or people working with an agent from issues. Includes the shell Git and gh exception. --- # GitHub GitHub does two unrelated jobs in Paperclip, and they are separate connections with separate credentials. ## Which do you want? | If you want | Set up | What it gives you | | --- | --- | --- | | Agents to read and act on repositories as part of their own work | **Use this connection as an agent tool** | GitHub actions an agent can call, and for a managed identity the credential the run's shell uses | | People to start and continue work by commenting in GitHub | **Chat with an agent** | A GitHub App that turns issue and pull-request comments into Paperclip tasks | Connecting one does not connect the other. [Set up the GitHub connector](github-setup.md) is the step-by-step procedure for both. Before you give an agent a GitHub identity, read the shell exception — it is the boundary most often misread. ## The shell exception Paperclip's per-action **Allowed** / **Ask first** / **Off** switches govern tool calls that go through Paperclip's tool gateway. When a GitHub connection is bound to an agent as a dedicated identity, that same identity is also handed to the agent's workspace shell, and shell commands do not go through the gateway. Paperclip states this when you change a GitHub permission: > **Danger:** Shell Git and `gh` use this account for the run and are not constrained by per-tool Ask-first controls. Three things this does **not** mean: - **It is not a claim about other connectors, in either direction.** This warning is about shell Git and `gh` on this connection. It says nothing about how any other connector behaves, and you should not read it as a promise that everything else is confined to the gateway — model-provider connections supply a credential rather than making tool calls at all, and messaging channels carry conversation over their own transport. [How connector access works](access-model.md) sets out which controls apply to which kind of connection. - **It is not a claim that the agent is unrestricted.** The ceiling is whatever the GitHub account can do: the repositories selected on the installation, and that account's permissions on them. Narrow the account, not the switches. - **Human approval is not code review.** An approved **Ask first** call means a person said yes to one API call. A pull request review is a separate control, on GitHub, done by a reviewer. Neither substitutes for the other. The practical consequence: for an agent that will push code, the limits that matter are GitHub-side — selected repositories, branch protection, required reviews — not Paperclip's per-tool switches. --- ## GitHub as an agent tool ### Choose a credential | Path | When to use it | Availability | | --- | --- | --- | | **Use this connection as an agent tool** | The default. Paperclip manages the GitHub App authorization, and the identity is also available to shell Git and `gh` | Only when the instance is enrolled with Paperclip Cloud and Cloud advertises the GitHub connector profile | | **Personal access token (advanced)** | No Cloud enrollment, or you want a token you control directly | Always | The two are not equivalent. A fine-grained personal access token carries the permissions you select on the token. The managed path's permissions come from the GitHub App registration and the repositories chosen on the installation — GitHub returns no OAuth scope list for it, so there is no scope string to inspect. If you need to reason precisely about permissions, a fine-grained token is easier to audit; if you need a durable identity for shell work, the managed path is the one that provides it. ### Choose an identity The managed path offers personal or dedicated-agent access. Its definition does not offer an organization-shared grant: | Setup choice | Effect | | --- | --- | | **My GitHub account** | *"Every agent may use your GitHub when you're responsible."* Choose **Only agents I choose** to narrow it | | **A dedicated account for an agent** | *"That agent always uses this account, regardless of who starts the run."* Commits and comments are attributable to the agent | A dedicated agent identity is the right choice when you want agent commits distinguishable from a person's. Creating one is a manager operation: *"Only connection managers can authorize a dedicated agent identity."* ### Repository access For the managed GitHub App path, repository scope is set in GitHub. The connection's identity card reflects the installation: - **Accessible GitHub repositories** lists the selected repositories, or shows **All current and future repositories** for an org-wide installation. - **Add More Repos on GitHub** and **Configure access on GitHub** link into GitHub's installation settings. - **Refresh access** re-reads the installation after you change it there. Prefer selected repositories for the managed App. An installation granting all current and future repositories widens as the organization grows. For a personal access token, review the token's resource owner, selected repositories, permissions, expiry, and any organization approval in GitHub. GitHub App installation controls do not set a PAT's scope. ### Actions GitHub's hosted server supplies the action list, so Paperclip does not ship a frozen copy. Read the live list on the connection's **Permissions** tab and use **Refresh actions** after GitHub changes it. What happens to an action GitHub adds depends on which credential path you took. On the **managed** path new and changed actions are held back until you turn them on. On a **personal access token** connection they become active under the policies already in force — so review the list after a refresh rather than assuming it can only narrow. [Set action permissions](action-permissions.md) has the full rule. Actions are classified read, write, or destructive and can be set **Allowed**, **Ask first**, or **Off** — remembering what those settings do and do not bound. See [Set action permissions](action-permissions.md). ### Try it Use a read against a repository you expect the selected credential to reach: ```txt Read the README in YOUR_ORG/YOUR_REPO and report its first heading. Do not change anything. ``` Compare the heading with the repository and inspect the task's connector call. For managed access, also check the GitHub App installation's selected repositories; for a PAT, check the token's repository selection and permissions. One successful read does not prove the credential cannot reach other repositories. Do not verify with a push, pull request, or merge. > **Note:** Illustrative task, not a recorded test result. --- ## GitHub as a channel People comment in an issue or pull request, mentioning the agent, and Paperclip creates a task. ### Before you connect - **Chat connectors** must be switched on for the instance. It is an experimental setting, off by default, enabled by an instance administrator under experimental settings. - Permission to create a GitHub App in the organization, and to install it. - The agent that will answer. ### What it needs You create one private GitHub App for this — with **Issues** and **Pull requests** read and write permission, the **issue_comment** and **pull_request_review_comment** events, and a webhook secret Paperclip generates — then give Paperclip its **App ID** and **private key (PEM)**. [Set up the GitHub connector](github-setup.md) has the numbered procedure. This route grants no repository tools. An agent reachable from issue comments cannot call GitHub actions unless you also set up the tool connection. ### Access Provider channel or repository access determines where a message can reach the integration; it does not by itself authorize agent work. Paperclip also checks the sender's linked identity and company membership. Linked users must be active non-viewer members. Unlinked senders depend on the connection's **Allow unlinked people** setting and any sponsor requirements. Review these controls before inviting people to use the agent. ### Try it 1. In a repository where the App is installed, open a scratch issue. 2. Comment, mentioning the agent, and ask it to confirm it is connected. 3. Expect a reply comment and a matching task in Paperclip. > **Note:** Procedure, not a recorded test result. Use a scratch repository or issue. --- ## Not the same as the workspace git setup [Connect an agent to a GitHub repo](../how-to/connect-agent-to-github.md) is a different job: pointing a project workspace at a remote, and matching Paperclip's review stage to GitHub's. That page remains the right one for the git and `gh` workflow itself. This connector is how the credential gets there. Use both. ## Troubleshooting | Problem | Likely cause | Fix | | --- | --- | --- | | **Use this connection as an agent tool** is not offered | The instance is not enrolled with Paperclip Cloud, or Cloud is not advertising the GitHub profile | Use **Personal access token (advanced)** | | **Chat with an agent** is not offered | **Chat connectors** is off for the instance | Ask an administrator to enable it | | The agent sees fewer repositories than expected | The installation does not include them | **Add More Repos on GitHub**, then **Refresh access** | | *"You don't have permission to reconnect this identity."* | The identity belongs to another person or agent | Ask its owner, or use your own | | Tool calls succeed but shell `git push` fails | The account's repository permissions, or branch protection | Check both on GitHub | | Comments do not create tasks | The App is not installed on that repository, or the events are not selected | Install it there and confirm the two comment events | | Webhook deliveries fail in GitHub | The webhook secret or URL does not match | Regenerate the secret in Paperclip and update the App | | **Needs attention** | The token expired or the installation was removed | Select **Reconnect** | ## Limitations The two routes are independent. Repository scope lives in GitHub on both. The managed tool path depends on Cloud enrollment; the channel path depends on the experimental chat setting. Paperclip cannot constrain shell Git or `gh` with per-action settings. ## Related guides - [Set up the GitHub connector](github-setup.md) - [Connect an agent to a GitHub repo](../how-to/connect-agent-to-github.md) - [Slack](slack.md) — the other mixed-purpose connector. - [How connector access works](access-model.md) - [Use separate accounts for people and agents](separate-accounts.md)