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

# Let AI Agents Open PRs and Issues on GitHub

> Connect GitHub with OAuth or a GitHub App so agents can push code, open PRs, and run workflows. Tokens are injected by the gateway, never by the agent.

## Overview

Buckle connects AI agents to GitHub so they can read and write code, open pull requests, manage issues, and trigger workflows. The gateway injects GitHub credentials into API requests automatically.

Buckle supports two ways to connect GitHub:

| Method | Access scope | Best for |
| - | - | - |
| **OAuth** | All repos the user can access | Personal use, quick setup |
| **GitHub App** | Only selected repos | Teams, organizations |

## What you will set up

* A GitHub connection through OAuth or a GitHub App
* Token injection on API calls and git-over-HTTPS
* Per-action allow, ask, or block controls for each agent

## Quick example

An agent calling the GitHub API through the gateway, with no token management needed:

```bash theme={null}
# List your repositories
curl -s "https://api.github.com/user/repos?per_page=5&sort=updated" | jq '.[].full_name'

# Create an issue
curl -s -X POST "https://api.github.com/repos/myorg/myrepo/issues" \
  -H "Content-Type: application/json" \
  -d '{"title": "Bug: login page timeout", "body": "The login page times out after 30s on slow connections."}'

# Open a pull request
curl -s -X POST "https://api.github.com/repos/myorg/myrepo/pulls" \
  -H "Content-Type: application/json" \
  -d '{"title": "Fix login timeout", "head": "fix/login-timeout", "base": "main"}'

# Trigger a workflow
curl -s -X POST "https://api.github.com/repos/myorg/myrepo/actions/workflows/deploy.yml/dispatches" \
  -H "Content-Type: application/json" \
  -d '{"ref": "main"}'
```

The agent makes standard GitHub API calls. The gateway injects the right authentication header automatically: `Bearer` token for API calls, Basic auth for git-over-HTTPS.

## OAuth

Connect your personal GitHub account. The agent gets access to all repositories you can see.

### Setup

**1. Open the app**

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

**2. Authorize**

Click **Connect GitHub**. You'll be redirected to GitHub to authorize Buckle. Review the permissions and click **Authorize**.

![Buckle connect window for GitHub on Cloud, showing the Connect to GitHub button.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/github/buckle-connect-github.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=41ae48bcaa4f229982846092cccc9d3e)

The GitHub connect window on Buckle Cloud.

### Self-hosted: use your own GitHub OAuth app

> [!NOTE]
>
> **Skip this section on Buckle Cloud.** It's only for self-hosted Buckle without `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` set, or if you want your own company name on GitHub's consent screen. For the GitHub App, see [GitHub App self-hosted](/docs/integrations/github-app.md#self-hosted).

> [accordion] 1. Create the OAuth app
>
> In GitHub, open **Settings** > **Developer settings** > **OAuth Apps** > **New OAuth App** (use your organization's settings to own it there). Name it `Buckle` and enter your homepage URL.
>
> ![GitHub Register a new OAuth app form with the name Buckle, a homepage URL, and the Buckle callback in the Redirect URI field.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/github/01-new-oauth-app.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=56ce42a9b9654dbf55ce5be3b78cf374)
>
> The new OAuth app form, filled in.

> [accordion] 2. Add the callback URL
>
> In Buckle, open **Settings** > **Apps** > **GitHub** > **Custom credentials** and copy the **Redirect URI**. In GitHub, paste it into **Redirect URI** and select **Register application**. GitHub OAuth apps don't take scopes here: Buckle requests `repo`, `user`, `gist`, `notifications`, `project`, `codespace`, and `workflow` when you connect.
>
> ![Buckle Custom credentials card for GitHub with the setup guide link, the Redirect URI and its copy button, and the client ID and secret fields.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/github/buckle-custom-credentials-github.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=654f574f3538386fe12611e2f22286f1)
>
> Copy the Redirect URI from Custom credentials in Buckle.

> [accordion] 3. Connect with your app
>
> Copy the **Client ID**, then select **Generate a new client secret** and copy it. Paste both into **Settings** > **Apps** > **GitHub** > **Custom credentials**, select **Save credentials**, then **Connect** and authorize in GitHub.

### Permissions

The OAuth connection requests these scopes:

| Scope | Name | Access |
| - | - | - |
| `repo` | Repositories | Read & write (code, issues, PRs) |
| `user` | Profile | Read (email, name, avatar) |
| `gist` | Gists | Read & write |
| `notifications` | Notifications | Read |
| `project` | Projects | Read & write |
| `codespace` | Codespaces | Read & write |
| `workflow` | Actions | Read & write (workflow files) |

> [accordion] More about OAuth: how it works, use cases, limitations
>
> **How it works**
>
> 1. You authorize Buckle via GitHub's OAuth flow
> 2. Buckle receives a long-lived access token and encrypts it
> 3. When an agent sends a request to `api.github.com`, the gateway injects the token as a `Bearer` header
> 4. For git operations over HTTPS (`github.com`), the gateway injects Basic auth credentials
>
> **Use cases**
>
> * Coding agents creating branches, committing code, and opening pull requests
> * Agents reviewing PRs and leaving comments
> * Triggering GitHub Actions workflows from an agent
> * Reading repository contents during code generation
>
> **Limitations**
>
> * The token has access to all repositories you can see, not just selected ones
> * No organizational visibility or approval flow
> * Token is long-lived until you revoke the connection

## GitHub App

For teams and organizations. A GitHub App gives you repo-level access control and organizational visibility. Org admins can see which repos are connected and approve or revoke access at any time.

### 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**.

**3. Install the app**

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

1. Select the organization or personal account
2. Choose **All repositories** or **Only select repositories**
3. Review the permissions

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

> [accordion] More about the GitHub App: how it works, use cases
>
> **How it works**
>
> 1. You install the GitHub App on your organization or account and select which repositories it can access
> 2. Buckle receives the app's private key and installation ID
> 3. The gateway signs a short-lived JWT and exchanges it for an installation access token (1hr TTL)
> 4. The token is injected into API requests and automatically refreshed when it expires
>
> **Use cases**
>
> * Organizations giving agents access to specific repos without exposing the full account
> * Teams where admins need visibility into which repos agents can access
> * Production deployments where token rotation should be automatic
> * Compliance environments where long-lived tokens are not acceptable

### Managing access

After connecting, you can change 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

## Comparison

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

## Per-action permissions

Once connected, the dashboard shows a permissions panel where you control what agents can do with GitHub. Each action has three modes: **Allow** (green), **Ask** (yellow, requires human approval), and **Block** (red, request is rejected).

**Read-only actions:**

| Action | Description |
| - | - |
| List repositories | Browse repos the account can access |
| Read repository | Read code, commits, branches |
| List issues | View issues on a repo |
| List pull requests | View open/closed PRs |

**Write / delete actions:**

| Action | Description |
| - | - |
| Create issue | Open new issues |
| Create pull request | Open PRs against a repo |
| Create comment | Comment on issues and PRs |
| Delete / close | Close issues, delete branches |

Use the **Read-only** preset to allow all read actions and block writes, or switch to **Custom** to configure each action individually.

## Controlling access

Both connection methods are 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:

* Rate limit API calls to stay within GitHub's rate limits
* Require manual approval for destructive operations (e.g., deleting branches)
* Scope a connection to specific repositories with a session policy

Everything is checked before credential injection, so a blocked request never touches your GitHub token.

## FAQ

> [accordion] How do I keep my GitHub token out of the agent's context?
>
> Don't set `GITHUB_TOKEN` or store a token in the agent's git config. Connect GitHub in Buckle, and the gateway adds `Bearer` auth for API calls and Basic auth for git-over-HTTPS at the proxy. See [How it works](/docs/how-it-works.md).

> [accordion] OAuth or GitHub App?
>
> OAuth reaches every repo you can access and suits personal use. A GitHub App reaches only selected repos and suits teams. See [Comparison](#comparison).

> [accordion] How do I reconnect or replace the GitHub credential?
>
> Reconnect from **Settings** > **Apps** > **GitHub** in the dashboard. Agents with access use the new credential automatically.

> [accordion] Can I require approval before an agent merges or pushes?
>
> Yes. Use [per-action permissions](#per-action-permissions) when you [grant](/docs/guides/agent-access.md) the connection, and [rules](/docs/guides/rules.md) for organization-wide guardrails.


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