> ## 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 Setup: Fine-Grained Repo Access

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

OneCLI 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 OneCLI:

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

<Steps>
  <Step title="Go to Connections">
    Open the OneCLI dashboard and navigate to **Connections** → **GitHub App**.
  </Step>

  <Step title="Configure credentials (self-hosted only)">
    If you're using OneCLI 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-onecli-url>/api/apps/github-app/callback`
    * **Redirect on update**: Checked
    * **Webhook**: Inactive (not required)
  </Step>

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

## 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 **Connections** → **GitHub App** in the OneCLI 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      |