> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Org-Approved GitHub Repo Access for AI Agents

> Give agents access to only selected repos with a GitHub App. Buckle mints short-lived installation tokens and injects them, so agents never see them.

## Overview

The GitHub App integration provides fine-grained, organization-approved access to repositories and resources. Unlike the [GitHub OAuth integration](/docs/integrations/github.md) 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:

| Permission | Access | Description |
| - | - | - |
| Contents | Read & Write | Code, commits, and branches |
| Pull requests | Read & Write | Create, review, and merge PRs |
| Issues | Read & Write | Create and manage issues |
| Actions | Read & Write | View runs and trigger workflows |
| Checks | Read & Write | Read CI results, create check runs |
| Metadata | Read | Repository metadata (always required) |

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.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/github-app/buckle-connect-github-app.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=a885fb63a6dd11f5250182ef9bcd1be2)

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

| Feature | GitHub App | GitHub OAuth |
| - | - | - |
| **Authorization** | Org admin installs the app | Individual user authorizes |
| **Repository scope** | Explicit per-repo grants | All repos the user can access |
| **Token lifetime** | 1 hour (auto-refreshed) | Long-lived |
| **Permissions** | Fine-grained per-resource | Scope-based |
| **Best for** | Teams, CI/CD, org-controlled access | Personal use, quick setup |

## Self-hosted: use your own GitHub App

> [!NOTE]
>
> **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.

> [accordion] 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.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/github-app/01-new-github-app.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=4db3b02bf5c74c5d501fa797859d70fd)
>
> 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.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/github-app/buckle-custom-credentials-github-app.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=42ef5b4cec9ffea16e709bb6b0a87648)
>
> Copy the Redirect URI from Custom credentials in Buckle.

> [accordion] 2. Generate a private key
>
> On the app's page, select **Generate a private key**. GitHub downloads a `.pem` file.

> [accordion] 3. Add the app to Buckle
>
> Paste the app into **Settings** > **Apps** > **GitHub App** > **Custom credentials**:
>
> | Field | Value |
> | - | - |
> | **App ID** | The numeric **App ID** on the app's page |
> | **App Slug** | The app's URL name, from `github.com/apps/<slug>` |
> | **Private Key** | The contents of the `.pem` file |
>
> 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.

> [accordion] 4. Connect
>
> 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](/docs/guides/agent-access.md) 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](/docs/guides/rules.md) add guardrails on top, like rate limits and blanket blocks. Everything is checked before credential injection, so a blocked request never reaches GitHub.

## FAQ

> [accordion] Do I need to rotate GitHub App tokens?
>
> No. Buckle generates short-lived installation access tokens from the app's private key and refreshes them automatically.

> [accordion] Does the agent see the private key or token?
>
> No. Both stay in Buckle, and the gateway injects the token at the proxy. See [How it works](/docs/how-it-works.md).

> [accordion] GitHub App or GitHub OAuth?
>
> Use the GitHub App when an organization needs to approve access and limit it to selected repositories. See [GitHub App vs GitHub OAuth](#github-app-vs-github-oauth).

> [accordion] How do I change which repos an agent can reach?
>
> Edit the app's installation in GitHub to add or remove repositories. Then use [per-agent access](/docs/guides/agent-access.md) to choose which agents get the connection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.