Skip to main content

​
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

1

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

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

Connect in OneCLI

Open the OneCLI dashboard, go to Connections > GitHub App, and provide:
OneCLI connect window for GitHub App on Cloud, showing the Connect to GitHub App button.

The GitHub App connect window on OneCLI Cloud.

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

​
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

​
Self-hosted: use your own GitHub App

Skip this section on OneCLI Cloud unless you want your own GitHub App. On self-hosted OneCLI without GITHUB_APP_ID set, this is required. You can enter the app in the dashboard, or set it once for the whole server.

1. Create the GitHub App

In GitHub, open Settings > Developer settings > GitHub Apps > New GitHub App (use your organization’s settings to own it there). Name it, set the homepage URL, and choose the repository permissions your agents need.In OneCLI, open Connections > GitHub App > Custom credentials and copy the Redirect URI. In GitHub, paste it into Redirect URI and into Setup URL, and keep Redirect on update ticked. Under Webhook, untick Active: OneCLI doesn’t use GitHub webhooks, so no webhook URL is needed. Then select Create GitHub App.
GitHub Create GitHub App form with the name OneCLI, a homepage URL, and the OneCLI callback as Redirect URI.

The new GitHub App form with the OneCLI Redirect URI. Fill Setup URL and untick Webhook Active further down the same form.

OneCLI Custom credentials card for GitHub App with the setup guide link, the Redirect URI and its copy button, and the App ID, App Slug, and Private Key fields.

Copy the Redirect URI from Custom credentials in OneCLI.

On the app’s page, select Generate a private key. GitHub downloads a .pem file.
Paste the app into Connections > GitHub App > Custom credentials:Select Save credentials. To set one app for the whole server instead, set GITHUB_APP_ID, GITHUB_APP_SLUG, and GITHUB_APP_PRIVATE_KEY and restart OneCLI.
Open Connections > GitHub App and select Connect. GitHub asks which account and repositories to install the app on.

​
Controlling access

Access is per agent: grant 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 add guardrails on top, like rate limits and blanket blocks. Everything is checked before credential injection, so a blocked request never reaches GitHub.