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
OneCLI connects AI agents to GitHub so they can read and write code, open pull requests, manage issues, and trigger workflows. The gateway injects GitHub credentials into API requests automatically. OneCLI supports two ways to connect GitHub:| Method | Plan | Access scope | Best for |
|---|---|---|---|
| OAuth | Free | All repos the user can access | Personal use, quick setup |
| GitHub App | Cloud | Only selected repos | Teams, organizations |
OAuth (Free)
Connect your personal GitHub account. The agent gets access to all repositories you can see.Setup
Permissions
The OAuth connection requests these scopes:| Scope | Name | Access |
|---|---|---|
repo | Repositories | Read & write (code, issues, PRs) |
user | Profile | Read (email, name, avatar) |
gist | Gists | Read & write |
notifications | Notifications | Read |
project | Projects | Read & write |
codespace | Codespaces | Read & write |
workflow | Actions | Read & write (workflow files) |
How it works
- You authorize OneCLI via GitHub’s OAuth flow
- OneCLI receives a long-lived access token and encrypts it
- When an agent sends a request to
api.github.com, the gateway injects the token as aBearerheader - For git operations over HTTPS (
github.com), the gateway injects Basic auth credentials
Use cases
- Coding agents creating branches, committing code, and opening pull requests
- Agents reviewing PRs and leaving comments
- Triggering GitHub Actions workflows from an agent
- Reading repository contents during code generation
Limitations
- The token has access to all repositories you can see, not just selected ones
- No organizational visibility or approval flow
- Token is long-lived until you revoke the connection
GitHub App (Cloud)
For teams and organizations. A GitHub App gives you repo-level access control and organizational visibility. Org admins can see which repos are connected and approve or revoke access at any time.Setup
Configure credentials (self-hosted only)
If you’re using OneCLI Cloud, skip this step. Platform credentials are pre-configured.For self-hosted, create a GitHub App and enter your App ID, App Slug, and Private Key.
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 workflows |
| Checks | Read & write | Read CI results, create check runs |
| Commit statuses | Read & write | Read and set status checks |
| Discussions | Read & write | Read and participate in discussions |
| Projects | Read & write | Manage project boards |
| Metadata | Read-only | Repository metadata (always granted) |
How it works
- You install the GitHub App on your organization or account and select which repositories it can access
- OneCLI receives the app’s private key and installation ID
- The gateway signs a short-lived JWT and exchanges it for an installation access token (1hr TTL)
- The token is injected into API requests and automatically refreshed when it expires
Use cases
- Organizations giving agents access to specific repos without exposing the full account
- Teams where admins need visibility into which repos agents can access
- Production deployments where token rotation should be automatic
- Compliance environments where long-lived tokens are not acceptable
Managing access
After connecting, you can change which repositories the app can access:- Go to Connections > GitHub App in the OneCLI dashboard
- Click Manage on the connection
- You’ll be taken to GitHub’s installation settings where you can add or remove repositories
Comparison
| OAuth | GitHub App | |
|---|---|---|
| Plan | Free | Cloud |
| Repo access | All repos the user can see | Only selected repos |
| Token lifetime | Long-lived | 1 hour (auto-refreshed) |
| Org visibility | Not visible to admins | Visible to org admins |
| Org approval | Not required | Required |
| Setup | One-click OAuth | Install app + select repos |
| Best for | Personal, quick start | Teams, production |
Controlling access with rules
Both connection methods work with OneCLI’s rules engine. You can create rules to:- Block write operations to
api.github.comfor read-only agents - Rate limit API calls to stay within GitHub’s rate limits
- Require manual approval for destructive operations (e.g., deleting branches)