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

   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.

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:

   • 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

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