Skip to main content

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

1

Create a GitHub App

Go to your GitHub organization settings (or personal settings) > Developer settings > GitHub Apps > New GitHub App.Configure the app with the permissions your agents need:Generate a private key from the app settings page.
2

Install the app

Install the GitHub App on your organization or user account. Choose which repositories to grant access to. You can select all repositories or specific ones.
3

Connect in Buckle

Open the Buckle dashboard, go to Settings > Apps > GitHub App, and provide:
Buckle connect window for GitHub App on Cloud, showing the Connect to GitHub App button.

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
Buckle uses these to generate short-lived installation access tokens automatically.

How it works

  1. Buckle stores your GitHub App credentials (App ID and private key)
  2. When an agent sends a request to api.github.com, the gateway generates a JWT signed with the private key
  3. The JWT is exchanged for a short-lived installation access token (expires in 1 hour)
  4. The access token is injected into the request as an Authorization header
  5. Expired tokens are refreshed automatically
Agents never see the private key or raw tokens.

GitHub App vs GitHub OAuth

Self-hosted: use your own GitHub App

Skip this section on Buckle Cloud unless you want your own GitHub App. On self-hosted Buckle without 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

In GitHub, open Settings > Developer settings > GitHub Apps > New GitHub App (use your organization’s settings to own it there). Name it, set the homepage URL, and choose the repository permissions your agents need.In Buckle, open Settings > Apps > GitHub App > Custom credentials and copy the Redirect URI. In GitHub, paste it into Redirect URI and into Setup URL, and keep Redirect on update ticked. Under Webhook, untick Active: Buckle doesn’t use GitHub webhooks, so no webhook URL is needed. Then select Create GitHub App.
GitHub Create GitHub App form with the name Buckle, a homepage URL, and the Buckle callback as Redirect URI.

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

Buckle Custom credentials card for GitHub App with the setup guide link, the Redirect URI and its copy button, and the App ID, App Slug, and Private Key fields.

Copy the Redirect URI from Custom credentials in Buckle.

On the app’s page, select Generate a private key. GitHub downloads a .pem file.
Paste the app into Settings > Apps > GitHub App > Custom credentials:Select Save credentials. To set one app for the whole server instead, set GITHUB_APP_ID, GITHUB_APP_SLUG, and GITHUB_APP_PRIVATE_KEY and restart Buckle.
Open Settings > Apps > GitHub App and select Connect. GitHub asks which account and repositories to install the app on.

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

No. Buckle generates short-lived installation access tokens from the app’s private key and refreshes them automatically.
No. Both stay in Buckle, and the gateway injects the token at the proxy. See How it works.
Use the GitHub App when an organization needs to approve access and limit it to selected repositories. See GitHub App vs GitHub OAuth.
Edit the app’s installation in GitHub to add or remove repositories. Then use per-agent access to choose which agents get the connection.