gigamcp/ docs

GitHub connector

Two flavours: GitHub App (recommended for organisations) and Personal Access Token (fastest for solo / small teams). Both result in the same indexed content; the App gets you finer-grained per-repo permissions, higher rate limits, and a clean audit log on the GitHub side.

Option A — GitHub App (recommended)

  1. In the Gigamcp admin console, open Connectors → Add → GitHub.
  2. Click Install on GitHub →. You'll be bounced to https://github.com/apps/gigamcp/installations/new. Pick a single repo, an entire org, or selected repos (you can change this later from the GitHub side).
  3. Approve the permissions GitHub asks for. The App requests:
    • contents: read — fetch file content for indexing.
    • metadata: read — required by GitHub for any installed App.
    • pull_requests: read, issues: read — optional, enables ingest of discussions and PR-context MCP tools.
  4. GitHub redirects you back to <your-tenant>.gigamcp.io/api/oauth/github-app/callback. We persist the installation id as a tenant-shared credential, then bounce you to /app/connectors?status=connected&provider=github-app.
  5. The connector status flips to Active once the first sync finishes (~1-5 min depending on repo size). The install is shared by the whole tenant — every member uses the same token.

Required role: the install flow is gated to tenant owners and admins. Regular members will see a 403 from /api/oauth/github-app/start — ask your tenant owner to run the install once, after which everyone benefits.

Rotation: we use the App's installation token flow, which rotates automatically every hour. Nothing for you to do.

Option B — Personal Access Token

  1. On GitHub: Settings → Developer settings → Personal access tokens → Tokens (classic). Create a token with the following scopes:
    • repo — required for private repos. Use public_repo only if you exclusively want to index public repos.
    • read:org — lets the connector enumerate repos by organisation. Without it the org-allowlist field below is silently ignored.
  2. Set an expiration. We recommend ≤ 90 days; Gigamcp surfaces a warning in the admin console 7 days before expiry.
  3. Paste the token into Connectors → Add → GitHub (the lower half of the form, below the App-install CTA). The token is stored KMS-encrypted in the per-tenant connector_credentials table — never returned to the browser.
  4. Optionally fill the Repository allowlist field — one owner/repo per line, with owner/* as a wildcard for the entire org. Empty = all repos visible to the credential. Allowlist entries are matched case-insensitively at MCP tool-call time and at RAG crawler time.
  5. Pick the visibility (Whole tenant / Group / Just me) and save.

What gets indexed

  • Markdown + reST + plain text files in the default branch — typically README.md, docs/**, specs/**, RFCs, etc.
  • Code files (TypeScript, Python, Go, …) — only where the connector is configured to index code (off by default; turn on per-source under Knowledge sources).
  • Issues + PR descriptions + comments — when the App is granted those scopes.

What does not get indexed

  • Binary files (images, archives) — they're skipped during ingest.
  • Branches other than the default branch.
  • Private repos the connector token doesn't have access to (we surface this as connector.test.failed in the audit log).

Audience visibility

Each repo can be a separate knowledge source with its own audience. Common patterns:

  • infra/* repos → audience Group: Engineering
  • handbook repo → audience Whole tenant
  • ~/notes personal repo → audience Just me (use the Personal connectors flow)