Set up the GitHub connector

Two separate procedures, because GitHub does two unrelated jobs. Pick the one you need:

• Set up GitHub as an agent tool — agents read and act on repositories.
• Set up chat from GitHub — people work with an agent from issue and pull-request comments.

For what each route governs, and the shell Git and gh exception, see GitHub. Read the exception before granting an agent a dedicated identity.

Set up GitHub as an agent tool

1. Decide the identity first

Deciding which identity and which repositories is the part worth slowing down for, because GitHub-side scope is the real limit on what an agent can do.

For anything that pushes code, a dedicated account is the better answer. Its actions are attributable, and revoking it does not disturb a person's own access.

2. Start the connection and pick a credential path

1. Select Connectors in the sidebar.
2. Find GitHub and select Connect.
3. Read the access line above the main button. It says who the connection signs in as and which agents can use it. To change either, select Change: answer Connect GitHub as with the identity from step 1, and choose Any agent or Only agents I choose. For a dedicated identity the agent question is already settled — Paperclip asks Which agent owns this GitHub account? instead.
4. Check the credential path. When the managed path is offered, setup starts on it; the token path sits under Change as the alternative:

The two branches do not share steps from here. Follow 3a or 3b, not both.

3a. Managed path — authorize and choose repositories in GitHub

1. Select Continue to GitHub and authorize.
2. On GitHub's installation screen, select the specific repositories the agent should reach. Avoid All current and future repositories unless that is genuinely the intent — Paperclip flags such an installation in the repository row, because it widens on its own as the organization grows.

Back in Paperclip, the identity card shows Accessible GitHub repositories. To change the list later use Add More Repos on GitHub or Configure access on GitHub, then Refresh access so Paperclip re-reads the installation.

This branch is the only one that produces a durable identity for shell Git and gh.

3b. Token path — create the token, then paste it

There is no authorization redirect and no GitHub installation screen on this branch. Repository scope lives on the token, so you set it while creating the token rather than afterwards in Paperclip.

1. In GitHub, go to Settings → Developer settings → Personal access tokens → Fine-grained tokens, and select Generate new token. Direct link: github.com/settings/personal-access-tokens/new.
2. Set the Resource owner to the account or organization that owns the repositories. If it is an organization, the token may need an organization owner's approval before it works — expect that delay rather than assuming the token is broken.
3. Under Repository access, choose Only select repositories and pick exactly the repositories agents should use.
4. Set an Expiration. A token that expires is a feature here; note the date, because the connection will stop working on it.
5. Grant repository permissions to match what you want agents to do, and no more. Read-only Contents, Metadata, Issues, and Pull requests is a sensible starting point; add write permissions deliberately, one at a time.
6. Generate the token and copy it. GitHub shows it once. It begins github_pat_.
7. Back in Paperclip, paste it into the GitHub token field and finish. The connection is complete at that point — there is nothing further to authorize.

Note: Because the permissions are the ones you ticked on the token, this path is the easier of the two to audit. What it does not give you is a durable shell identity: for that, use the managed path.

To change repository scope later, edit the token in GitHub or issue a new one and reconnect. Refresh access re-reads an installation and does not apply here.

4. Set the actions

On the Permissions tab, work down the list: reads Allowed; writes and destructive actions Ask first or Off until you have watched the agent work.

Paperclip shows the shell warning when you change a permission on a dedicated GitHub identity. Read it as written: shell Git and gh use that account and are not bounded by these switches.

5. Put the real guardrails on GitHub

Because the shell is not gated by action permissions, the controls that matter for an agent with push access live on GitHub:

• For the managed App, grant selected repositories. For a PAT, restrict repository selection and token permissions in GitHub.
• Protect the default branch: require a pull request, and require a review from someone other than the agent.
• Require status checks to pass before merge.

Paperclip's execution policy can also require a review stage on the Paperclip issue, but a Paperclip review stage and a GitHub branch protection rule are separate controls. Set both if merges matter.

6. Verify with a read

As the agent you intend to use, ask it to read a known file in an intended repository. Compare the content and inspect the task's connector call. Check managed App installation settings or, for a PAT, its repository selection and permissions separately. A successful read verifies that operation, not the entire access boundary.

Do not verify with a push, a pull request, or a merge.

Set up chat or a PR review bot from GitHub

Experimental: Enable Chat connectors in the instance's experimental settings before starting this path.

The review bot has its own entry on the Connectors page, GitHub Code Review Bot, separate from the GitHub entry for repository tools. Selecting it goes straight to choosing the agent.

Follow Set up a GitHub review bot for the complete chat setup, including an optional Storybook reviewer. It covers manifest registration, separate App installation and repository enablement, effective agent tools, personal account linking, and a real PR test. Choose authorized mentions only if you want a chat bot without automatic reviews.

Read Understanding GitHub PR review bots first if you are deciding whether reviews should run automatically or block merges. Installing the App does neither by itself.

Troubleshooting

More in Verify a connector and fix a broken one.

Related guides

• Understanding GitHub PR review bots

• Set up a GitHub review bot

• GitHub

• Connect an agent to a GitHub repo

• Use separate accounts for people and agents

• Set action permissions