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

# GitHub App Setup: Fine-Grained Repo Access

> Install and configure the Buckle GitHub App for fine-grained repo access. Supports org-level approval and per-repo scoping.

Buckle supports two ways to connect GitHub:

| Method | Best for | Access scope |
| - | - | - |
| **GitHub OAuth** | Quick personal setup | All repos the user can see |
| **GitHub App** | Teams and organizations | Only selected repos |

GitHub App connections give you repo-level access control and organizational visibility. Org admins can see which repos are connected and approve or revoke access at any time.

## How it works

When you connect a GitHub App through Buckle:

1. You're redirected to GitHub to install the app on your account or organization
2. You choose exactly which repositories the app can access
3. Buckle receives a short-lived installation token (1 hour TTL) that's automatically refreshed
4. Your agents use this token to interact with GitHub APIs, scoped to only the repos you selected

## Setup

**1. Open the app**

Open the Buckle dashboard and navigate to **Settings** > **Apps** > **GitHub App**.

**2. Configure credentials (self-hosted only)**

If you're using Buckle Cloud, skip this step. Platform credentials are pre-configured.

For self-hosted deployments, [create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) and enter your **App ID**, **App Slug**, and **Private Key** in the custom credentials form.

Your GitHub App should have:

* **Setup URL**: `https://<your-buckle-url>/api/apps/github-app/callback`
* **Redirect on update**: Checked
* **Webhook**: Inactive (not required)

**3. Install the app**

Click **Connect GitHub App**. You'll be redirected to GitHub where you can:

* Select the organization or personal account
* Choose **All repositories** or **Only select repositories**
* Review the permissions the app requests

Click **Install** to complete the connection.

## Permissions

The GitHub App requests only 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 workflow dispatches |
| Checks | Read & write | Read CI results, create check runs |
| Commit statuses | Read & write | Read and set status checks on commits |
| Discussions | Read & write | Read and participate in discussions |
| Projects | Read & write | Manage project boards |
| Metadata | Read-only | Repository metadata (always granted) |

Permissions are set at the app level. To change them, update the app's configuration in your [GitHub App settings](https://github.com/settings/apps).

## Managing access

After connecting, you can modify which repositories the app can access:

1. Go to **Settings** > **Apps** > **GitHub App** in the Buckle dashboard
2. Click **Manage** on the connection
3. You'll be taken to GitHub's installation settings where you can add or remove repositories

## GitHub App vs OAuth App

| | GitHub App | OAuth App |
| - | - | - |
| **Repo access** | Only selected repos | All repos the user can see |
| **Token lifetime** | 1 hour (auto-refreshed) | Long-lived |
| **Org visibility** | Visible to org admins | Invisible |
| **Org approval** | Required | Not required |
| **Best for** | Teams, production | Personal, quick start |


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