ghp acts as a transparent proxy for GitHub's API and web endpoints. Your administrator configures DNS so that api.github.com and github.com resolve to the ghp server on your network. Agents set GH_TOKEN to a ghp-issued token and make standard GitHub API calls — no code changes or special SDKs required.

Request Flow

sequenceDiagram
    participant Agent as Agent<br/>(GH_TOKEN=ghx_xxx)
    participant ghp as ghp<br/>(api.github.com virtualhost)
    participant GitHub as GitHub<br/>(real api.github.com)

    Agent->>ghp: GET /repos/owner/repo/pulls
    ghp->>ghp: Validate token
    ghp->>ghp: Check scope
    ghp->>ghp: Inject real credential
    ghp->>GitHub: GET /repos/owner/repo/pulls
    GitHub-->>ghp: 200 OK
    ghp-->>Agent: 200 OK

For each request, the proxy:

1. Validates the token and checks it hasn't expired or been revoked
2. Verifies the request targets an allowed repository and permitted operation
3. Swaps in the real GitHub credentials (stored server-side, encrypted at rest)
4. Forwards the request to GitHub and returns the response unchanged

Virtualhost Routing

ghp serves four distinct roles depending on which hostname the request arrives on:

In TLS mode (recommended for production), ghp terminates TLS directly and uses SNI to select the correct certificate for each hostname. In plain HTTP mode (for development or behind a reverse proxy), routing is based on the Host header alone.

Security Model

• Token isolation — agents never see real GitHub credentials; they only hold short-lived ghp tokens
• Scope enforcement — tokens can be restricted to specific repositories and permission levels
• Encryption at rest — for SQLite and PostgreSQL backends, all stored GitHub credentials are encrypted with AES-256-GCM using a server-managed key. For the Vault backend, Vault provides encryption at rest natively, so no application-level encryption key is required
• Audit trail — all requests produce structured JSON access logs (method, path, status, duration). API proxy requests additionally produce structured JSON audit log entries ("logger":"audit") that include token, user, session, repository details, and request context. Token lifecycle events (creation, revocation) also emit audit log entries but may omit repository and request-related fields. Audit logs are written to the same output stream as access logs. Capturing and indexing these logs is the responsibility of the deployment environment (e.g. Splunk, Elastic, Datadog)
• Expiration — tokens have a configurable lifetime (default 24 hours, up to a server-configured maximum; default maximum 7 days)
• Revocation — tokens can be revoked immediately from the CLI or web dashboard
• Border policy — administrators can block specific GitHub token types from passing through the proxy (see Token Type Border Policy)

Feature Summary

Token Scoping

Tokens can be scoped to specific repositories and permission levels, ensuring agents only access what they need. Open-scoped tokens (no restrictions) are also supported when full access is appropriate.

See Token Scoping for details.

Blocking Anonymous Git Traffic

Administrators can block unauthenticated git operations (clone, fetch, ls-remote) from passing through the proxy. When enabled, requests without credentials are rejected immediately rather than being forwarded to GitHub.

block:
  anonymous_git: true

This setting can be changed without restarting the server (see Configuration).

Release Download Controls

GitHub release assets (binaries, installers, archives) are fetched via direct HTTPS downloads, outside the scope model that ghp applies to API traffic. The release controls feature lets administrators block or redirect these downloads.

See Release Download Controls for configuration and details.

Copilot Passthrough

Traffic to *.githubcopilot.com is forwarded transparently. Copilot clients manage their own credentials, so ghp does not intercept tokens or enforce scopes on this traffic. All Copilot requests are still logged and counted in metrics for full visibility.

Git Cache

For frequently-cloned repositories, ghp can cache git objects locally and serve subsequent clone/fetch requests from cache. This reduces load on GitHub and improves clone performance. Caching is opt-in per repository and always verifies GitHub access before serving cached data.

See Git Cache for configuration and details.

Multi-App Support

ghp supports multiple GitHub Apps simultaneously. Each app can have its own set of installations, and agent tokens (gha_) can be scoped to a specific app. This is useful for organizations that need to separate concerns across different GitHub Apps (e.g., CI vs. code review vs. deployment).

Apps are managed dynamically via the admin UI or API (/api/apps). Changes take effect immediately — no restart or config reload is needed.

On first startup, if no apps exist in the database, the config-based GitHub App (github.app_id, github.private_key, etc.) is automatically seeded as a default App record in the store. Any existing agent tokens that have no app association are backfilled to point to the newly created default app. After seeding, all app management goes through the store — the config-based values are not used as an independent provider in parallel with store apps.

If apps exist in the store but none can be loaded (e.g. all private keys are invalid), agent token creation returns HTTP 503 rather than creating tokens that would fail at use-time.

Storage Backends

ghp supports three storage backends:

• SQLite — single-file database, ideal for development and small deployments
• PostgreSQL — production-grade relational database
• HashiCorp Vault — secrets-native storage using KV v2 secrets engine with AppRole authentication

All backends implement the same Store interface and provide identical feature parity. The Vault backend stores all data (users, tokens, apps) as KV v2 secrets and uses index entries for lookups. It does not require SQL migrations and does not need an encryption_key (Vault encrypts at rest).

See Configuration for backend-specific settings and Vault Backend for a complete Vault setup guide.

OAuth Broker

ghp can act as an OAuth broker for other services on your network, allowing them to authenticate users via GitHub without needing their own OAuth credentials.

See OAuth Broker for integration details.