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

1. Go to Connections

   Open the OneCLI dashboard and navigate to Connections → GitHub App.

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

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.

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