Skip to main content

GitHub Connector

The GitHub connector is a governed, read-only integration that imports and continuously syncs content from GitHub repositories into the Keeptrusts Knowledge Base. Two auth models are supported: a GitHub App (recommended for organization-wide access) and a Personal Access Token (PAT, for single-user or fallback use). Connector-backed files surface sync health in the Knowledge Base file inspector and support agent, task, and runner bindings.

Use this page when​

  • You are setting up a GitHub connector for the first time using the GitHub App model or a PAT.
  • You need to understand the difference between the GitHub App and PAT auth models.
  • You need to troubleshoot GitHub connector authorization or capability discovery.
  • You want to understand how continuous sync works for GitHub repository content.
  • You are a platform operator configuring GitHub credentials on the API service.

Primary audience​

  • Primary: Technical Engineers
  • Secondary: AI Agents, Technical Leaders

Prerequisites​

GitHub App model (recommended):

  • Access to the Connectors page in the Keeptrusts console.
  • Confirmation from your platform operator that KEEPTRUSTS_CONNECTOR_GITHUB_APP_ID and KEEPTRUSTS_CONNECTOR_GITHUB_PRIVATE_KEY are configured on the API service.
  • The GitHub App installed on the target GitHub organization or repository.

PAT fallback model:

  • Access to the Connectors page in the Keeptrusts console.
  • A GitHub Personal Access Token with at least repo (read) or contents:read fine-grained permission for the target repository.
  • Confirmation from your platform operator that PAT fallback is enabled for GitHub connectors in your deployment.

Auth models​

GitHub App (primary)​

GitHub App authentication is the recommended model for organization-wide access. A single GitHub App can be installed on an organization and granted access to multiple repositories without tying access to an individual user account. If the user who installed the App leaves the organization, access is not affected.

Benefits:

  • Organization-level installation — no individual user token required
  • Fine-grained repository and permission scope control
  • App tokens rotate automatically — no manual token refresh
  • Audit events recorded against the App, not a person

Personal Access Token (PAT)​

PAT authentication is a fallback for single-user connectors or environments where a GitHub App cannot be installed. PATs are tied to a GitHub user account and expire or can be revoked by the user.

Use PAT when:

  • The GitHub App model is not available in your deployment
  • You are connecting to a personal GitHub repository
  • You need a quick fallback for testing

PAT limitations:

  • Tied to a GitHub user account — if the user leaves, the token stops working
  • Classic PATs have broad scope; prefer fine-grained PATs scoped to specific repositories
  • No automatic rotation — you must rotate and update the connector manually when the PAT expires

Setup steps​

GitHub App model​

  1. Open Connectors in the Keeptrusts console.
  2. Click Add connector.
  3. Enter a connector Name.
  4. Choose GitHub as the provider.
  5. Choose the connector Scope.
  6. Click Create connector.
  7. Open the connector detail page.
  8. Click Authorize and complete the GitHub App installation or authorization flow for the target organization or repository.
  9. Return to the connector detail page and click Refresh capabilities.

PAT fallback model​

  1. Confirm with your platform operator that PAT fallback is enabled for GitHub connectors in your deployment.
  2. Open Connectors in the Keeptrusts console and create a GitHub connector.
  3. Follow the PAT credential handoff flow exposed by your deployment to supply the token for that connector.
  4. Open the connector detail page and click Refresh capabilities.

After completing either setup, the connector status should be active and the capability snapshot should list the accessible repositories and scopes.

Platform operator: configure GitHub credentials​

GitHub App:

  1. Create a GitHub App in your GitHub organization or personal account settings.
  2. Generate a private key for the App.
  3. Set KEEPTRUSTS_CONNECTOR_GITHUB_APP_ID to the numeric App ID on the API service.
  4. Set KEEPTRUSTS_CONNECTOR_GITHUB_PRIVATE_KEY to the PEM-encoded private key on the API service.
  5. Install the GitHub App on the target organization or repositories.

PAT fallback:

  1. Generate a GitHub Personal Access Token (fine-grained preferred) with contents:read permission for the target repositories.
  2. Set KEEPTRUSTS_CONNECTOR_GITHUB_PAT on the API service as the fallback credential.

Continuous sync​

Once a GitHub repository file is imported into the Knowledge Base, Keeptrusts tracks the source reference and syncs content changes automatically. The sync rail in the Knowledge Base file inspector shows:

  • healthy — the file is in sync with the GitHub source
  • warning — a transient issue was detected; Keeptrusts will retry automatically
  • error — sync failed; check credentials and repository permissions
  • paused — sync was manually paused by a user
  • unknown — sync state has not been established yet

Recovery actions available from the sync rail: Retry sync, Resync, Pause sync, Resume sync.

GitHub App tokens rotate automatically. PAT-backed connectors stop syncing when the PAT expires — you must replace the token through your deployment's PAT handoff flow and click Refresh capabilities.

Troubleshooting​

ProblemWhat to check
GitHub App connector shows errorConfirm the GitHub App is installed on the target org or repo; confirm KEEPTRUSTS_CONNECTOR_GITHUB_APP_ID and KEEPTRUSTS_CONNECTOR_GITHUB_PRIVATE_KEY are set correctly on the API service
PAT connector moves to expiredThe PAT expired or was revoked — generate a new PAT, replace it through your deployment's PAT handoff flow, and click Refresh capabilities
Capabilities stay emptyClick Refresh capabilities; confirm the GitHub App is installed or the PAT has contents:read permission on the target repositories
Connector does not become active after App installConfirm the GitHub App installation flow completed for the correct organization or repository; check that KEEPTRUSTS_CONNECTOR_GITHUB_APP_ID matches the installed App
Sync shows error in the file inspectorCheck the error message in the sync rail; common causes include branch deletion, repository visibility changes, and App suspension
Fine-grained PAT cannot read private repositoriesConfirm the PAT has contents:read permission for each private repository and is not scoped to only public repositories

For AI systems​

  • Canonical terms: Keeptrusts GitHub connector, GitHub App auth, Personal Access Token (PAT) auth, connector authorization, capability discovery, continuous sync, sync health.
  • Auth models: GitHub App (primary, org-wide, token rotation); PAT (fallback, user-scoped, manual rotation).
  • Platform operator setup: use the GitHub App model as the primary path; some deployments also allow a PAT fallback for single-user or emergency use.
  • Connector statuses: pending, active, expired, revoked, error.
  • Sync states: healthy, warning, error, paused, unknown.
  • Related pages: Connectors overview, Knowledge Base, Settings and Gateway Config.

For engineers​

  • Use the GitHub App model for all production and organization-wide deployments — it avoids personal token dependency and supports automatic token rotation.
  • When generating the GitHub App private key, store the PEM file securely and set KEEPTRUSTS_CONNECTOR_GITHUB_PRIVATE_KEY to the full PEM content (including header and footer lines).
  • For fine-grained PATs, scope to contents:read on specific repositories rather than using classic PATs with broad repo scope.
  • After replacing a PAT for a connector, click Refresh capabilities to confirm the new token works before relying on sync.
  • GitHub App token rotation is handled automatically by Keeptrusts — no manual intervention is needed for App-based connectors.

For leaders​

  • GitHub connector support brings repository documentation, policy files, and code context into governed AI context.
  • The GitHub App model removes personal token dependency — access does not break when team members change roles or leave.
  • Fine-grained PAT support lets teams adopt the connector incrementally without requiring organization-level App installation.
  • Sync health tracking ensures the Knowledge Base reflects the current state of repository content, reducing the risk of agents referencing outdated documentation.

Next steps​