GitHub Setup Guide

Enables your agent to read repositories, create issues, open pull requests, and post comments on GitHub.

Prerequisites

• A GitHub account
• Access to the repositories you want the agent to interact with

Step 1: Create a Personal Access Token

Fine-Grained Token (recommended)

Fine-grained tokens let you scope access to specific repositories with granular permissions.

1. Go to github.com/settings/tokens?type=beta
2. Click Generate new token
3. Set a token name (e.g., "Carapace Agent")
4. Set expiration (90 days recommended — you'll need to rotate before it expires)
5. Under Repository access, select Only select repositories and choose the repos the agent needs
6. Under Permissions > Repository permissions, enable:
   • Contents: Read and write (read/push code)
   • Issues: Read and write (create/comment on issues)
   • Pull requests: Read and write (create/review PRs)
   • Metadata: Read-only (always required, auto-selected)
7. Click Generate token
8. Copy the token (starts with github_pat_) — it's shown only once

Classic Token (legacy)

1. Go to github.com/settings/tokens
2. Click Generate new token (classic)
3. Enable scopes: repo, read:user, read:org
4. Click Generate token
5. Copy the token (starts with ghp_)

Step 2: Connect in Carapace

1. Go to Dashboard > Connections
2. Find GitHub and click Connect
3. Paste your token in the Personal Access Token field
4. Click Save Credentials

Credential Fields Reference

Gotchas

Fine-grained tokens are scoped to specific repos: Unlike classic tokens, fine-grained tokens only work on the repositories you selected during creation. If the agent tries to access a repo not in the token's scope, it will get a 404 (not 403).

Classic repo scope is over-privileged: A classic token with repo scope grants read/write access to ALL your repositories (public and private). Prefer fine-grained tokens to limit blast radius.

Tokens expire: Both token types can have expiration dates. Fine-grained tokens require one. Set a calendar reminder to rotate the token before it expires, then update it in the Carapace dashboard.

Organization repositories may need approval: If the repo belongs to a GitHub organization with SSO or token policies, the org admin may need to approve the token. You'll see a prompt to "Configure SSO" next to the token in your settings.

Troubleshooting

404 on repository access

Your fine-grained token doesn't include that repository. Edit the token to add it, or create a new token with the correct repo scope.

401 Unauthorized

Token is expired or invalid. Check expiration date in GitHub settings and regenerate if needed.

See Also

• GitHub: Creating fine-grained PATs
• GitHub: Token scopes