OrgMCP/ 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 OrgMCP 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>.orgmcp.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; OrgMCP 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 — unless a branch allowlist is configured on the connector (see below).
  • Private repos the connector token doesn't have access to (we surface this as connector.test.failed in the audit log).

Ingest filters (per-repo)

On the connector's Sources tab you can attach per-repo ingest filters that are read by the GitHub crawler on every sync. Each filter lives under connectors.settings.ingestFilters["owner/name"] and is applied on top of the source-level paths field.

  • Path allowlist — array of path prefixes (e.g. docs/, README.md). Intersected (AND-ed) with the source's own paths; both must allow a file for it to be indexed. Leave empty to skip the filter.
  • Branch allowlist — array of branch names (without the refs/heads/ prefix). When set, the crawler walks each listed branch instead of the source-level ref/default-branch path. The global per-repo file cap (1000) is shared across all branches, so very wide allowlists silently truncate.
  • Filters apply to: branch & path allowlists only in v1. sinceDate is reserved for the commit-ingest path coming in a follow-up — the PATCH endpoint accepts it (so the FE form stays unchanged) but the current tree-walk crawler does not consume it. See Wave 1.5 Track C follow-up below.

Documents emitted under an active filter carry metadata.connectorFilters = { branchAllowlist, pathAllowlist } so a downstream audit can verify which filter shaped the snapshot. Repos with no filter configured produce a byte-identical document set to the pre-Track-C crawler.

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)