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

# GitHub App Integration: Org-Approved Repository Access

> Fine-grained, organization-approved access to repositories through GitHub App installation tokens. Tokens are refreshed and injected automatically.

## Overview

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

## Setup

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Connect in OneCLI">
    Open the OneCLI dashboard, go to **Connections** > **GitHub App**, and provide:

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

    OneCLI uses these to generate short-lived installation access tokens automatically.
  </Step>
</Steps>

## How it works

1. OneCLI 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 setup

For self-hosted deployments, set these environment variables:

* `GITHUB_APP_ID`: Numeric App ID
* `GITHUB_APP_SLUG`: URL-friendly app name
* `GITHUB_APP_PRIVATE_KEY`: PEM private key contents

## Controlling access with rules

Use OneCLI's [rules engine](/guides/rules) to add further restrictions beyond GitHub App permissions. For example, block force-push operations or require manual approval for merging PRs. Rules are evaluated before credential injection.