Overview
The GitHub App integration provides fine-grained, organization-approved access to repositories and resources. Unlike the GitHub OAuth integration which uses personal access tokens, GitHub Apps are installed at the organization or user level with explicit repository and permission grants. This is the recommended approach for teams that need organizational control over what repositories and permissions agents can access.What you will set up
- A GitHub App with the permissions your agents need
- An installation on the repositories agents should reach
- Short-lived installation tokens generated and injected by Buckle
Setup
Create a GitHub App
Install the app
Connect in Buckle

The GitHub App connect window on Buckle Cloud.
- App ID: The numeric ID from your GitHub App settings
- App Slug: The URL-friendly name from your GitHub App settings
- Private Key: The PEM private key you generated
How it works
- Buckle stores your GitHub App credentials (App ID and private key)
- When an agent sends a request to
api.github.com, the gateway generates a JWT signed with the private key - The JWT is exchanged for a short-lived installation access token (expires in 1 hour)
- The access token is injected into the request as an
Authorizationheader - Expired tokens are refreshed automatically
GitHub App vs GitHub OAuth
Self-hosted: use your own GitHub App
GITHUB_APP_ID set, this is required. You can enter the app in the dashboard, or set it once for the whole server.1. Create the GitHub App
1. Create the GitHub App

The new GitHub App form with the Buckle Redirect URI. Fill Setup URL and untick Webhook Active further down the same form.

Copy the Redirect URI from Custom credentials in Buckle.
2. Generate a private key
2. Generate a private key
.pem file.3. Add the app to Buckle
3. Add the app to Buckle
GITHUB_APP_ID, GITHUB_APP_SLUG, and GITHUB_APP_PRIVATE_KEY and restart Buckle.4. Connect
4. Connect
Controlling access
Access is per agent: grant the connection to each agent that needs it, choosing per tool what runs freely, what needs human approval, and what stays blocked — a read-only agent is a single grant. Organization rules add guardrails on top, like rate limits and blanket blocks. Everything is checked before credential injection, so a blocked request never reaches GitHub.FAQ
Do I need to rotate GitHub App tokens?
Do I need to rotate GitHub App tokens?
Does the agent see the private key or token?
Does the agent see the private key or token?
GitHub App or GitHub OAuth?
GitHub App or GitHub OAuth?
How do I change which repos an agent can reach?
How do I change which repos an agent can reach?