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.
Overview
The GitHub App integration provides fine-grained, organization-approved access to repositories and resources. Unlike the GitHub OAuth integration 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
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:
Generate a private key from the app settings page.
| 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) |
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.
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
How it works
- OneCLI stores your GitHub App credentials (App ID and private key)
- When an agent sends a request to
api.github.com, the gateway generates a JWT signed with the private key - The JWT is exchanged for a short-lived installation access token (expires in 1 hour)
- The access token is injected into the request as an
Authorizationheader - Expired tokens are refreshed automatically
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 IDGITHUB_APP_SLUG— URL-friendly app nameGITHUB_APP_PRIVATE_KEY— PEM private key contents