Skip to content
Leverage AI Developer Support

GitHub Connector

Use this page when you need the implementation shape and GitHub-side setup details for the GitHub connector family. For shared connector behavior, start with Connectors Overview and Provider Auth And Setup.

Runtime Shape

Section titled “Runtime Shape”
  • Implemented modes: fixed live
  • Auth binding: Better Auth generic OAuth provider id github
  • Callback URI examples:
    • http://localhost:3001/api/auth/oauth2/callback/github
    • https://auth.example.com/api/auth/oauth2/callback/github
  • Setup console URL:
  • Current OAuth App credentials:
    • GITHUB_CLIENT_ID
    • GITHUB_CLIENT_SECRET
  • Required connector scopes:
    • repo
    • read:user
    • user:email

Connector Keys

Section titled “Connector Keys”
Connector Key Live domain and tool
GitHub Repositories github-repositories code-repository through code-repository-live-query
GitHub Issues github-issues work-item through work-item-live-query
GitHub Pull Requests github-pull-requests work-item through work-item-live-query

Implementation Overview

Section titled “Implementation Overview”
  • The three GitHub connector keys are one provider-family rollout that shares the Better Auth linked GitHub account and optional provider-family repository limit.
  • github-repositories is the first code-repository live provider. It normalizes repository metadata, code search results, bounded file reads, and recent commits into the shared repositories, codeFiles, and commits result groups.
  • github-issues and github-pull-requests reuse the shared work-item live contract. GitHub issue and PR adapters preserve owner/repo#number, state, authors, assignees, labels, milestones, comments, PR reviewers, review comments, branch refs, changed files, timestamps, and GitHub URLs as provider-neutral source metadata. Answer prose should use labels such as owner/repo#123; open links stay in structured source actions.
  • GitHub label and milestone inventory questions use GET /repos/{owner}/{repo}/labels and GET /repos/{owner}/{repo}/milestones through the shared work-item facet path. Answers must distinguish available/configured repository labels and milestones from facets currently attached to returned issue or PR rows.
  • Private chat routes through canonical domain tools (code-repository-live-query and work-item-live-query) instead of provider-specific tool ids. Provider-specific behavior stays inside the GitHub REST client and GitHub live adapters.
  • Repository limits are connector-agnostic provider-family resource scoping. An account-level GitHub repository limit is inherited by Repositories, Issues, and Pull Requests unless a specific connector has its own explicit repository selection override.
  • Deterministic eval packs cover repository/code/file/commit prompts, GitHub issue and PR prompts, cross-domain source switching, follow-ups, no-match cases, and unsupported GitHub products. Local prompt-pack checks exercise the same connector keys through browser-backed chat when a developer has representative GitHub data connected.
  • Local chat verification should include ordinary all-scope private chats as well as focus-mode checks. For repository/code prompts, Sources should show the code-repository GitHub path being checked; for issues and PRs, Sources should show the shared work-item path. Focus mode passing is not enough if all-scope source selection skips GitHub.
  • Verification must ask for GitHub facets directly, not only objects. Include both “which labels/milestones are available/configured?” and “which returned issues or PRs have this label or milestone?” prompts. Issue/PR labels, milestones, assignees, authors, reviewers, review state, branch refs, comments, and changed files should remain work-item evidence even when the same repository also has code-repository evidence.
  • Milestone inventory is provider-bounded and includes milestone due dates when GitHub returns them. Direct named-repository checks should not report a generic no-result if GitHub rejects the repository lookup; surface it as an inaccessible repository/source coverage gap. If bounded repository discovery finds same-name accessible repositories, mention them only as possible full-name suggestions.
  • GitHub data is live-only in this rollout. File contents, snippets, issue bodies, comments, PR reviews, and changed-file lists are transient grounding evidence and are not synced into indexed storage or embeddings.

Provider-Specific Gotchas

Section titled “Provider-Specific Gotchas”
  • GitHub connector definitions use the shared connector OAuth link route (/api/auth/oauth2/link), so GitHub must be present in apps/auth/src/genericOAuthProviders.ts; env credentials alone are not enough to mount the generic link route.
  • GitHub local OAuth App callbacks can use http://localhost:3001/api/auth/oauth2/callback/github. If AUTH_PUBLIC_BASE_URL is set for another provider such as Slack, leave github out of AUTH_CONNECTOR_OAUTH_PUBLIC_BASE_URL_PROVIDER_IDS so GitHub remains on the localhost callback.
  • GitHub’s “redirect_uri is not associated with this application” warning means the OAuth App registration does not accept the redirect URI sent in the authorize request. Register the canonical callback /api/auth/oauth2/callback/github, or for an existing local dev OAuth App registered to http://localhost:8080/api/v1/data/github/callback, temporarily set AUTH_OPEN_WEBUI_OAUTH_CALLBACK_BRIDGE_PROVIDER_IDS=github. When setting this through root .env.common, run bun run env:refresh and restart the dev stack so apps/auth/.env receives it. Clearing the allowlist or moving the bridge base URL back to its default also needs bun run env:refresh so stale app-local bridge values are removed. If the user is already signed in to GitHub, this warning can appear even when an unauthenticated browser check only reaches GitHub’s login page.
  • The temporary local callback bridge does not require running the old Open WebUI stack and is ignored unless auth runs with NODE_ENV=development. When enabled with the default local origin, the auth service starts a lightweight listener on http://localhost:8080 for old callback paths only. If that port is already occupied, stop the process using it or remove github from the bridge allowlist.
  • The temporary local callback bridge is provider-specific and not permanent GitHub connector configuration. Leaving github out of AUTH_OPEN_WEBUI_OAUTH_CALLBACK_BRIDGE_PROVIDER_IDS keeps GitHub on the canonical callback path, even when another provider uses the bridge.
  • GitHub is live-only in this repo. There is no GitHub indexed sync path, Meltano tap, embeddings path, or retained GitHub code/issue/PR snapshot.
  • The current product path uses a GitHub OAuth App. GitHub OAuth Apps do not offer a private-repository read-only scope, so repo is broad and write-capable at the provider scope level.
  • The app enforces read-only behavior at runtime: no write UI, no write tools, no mutating REST calls, no webhooks, and no merge, comment, review, branch-update, file-write, workflow, delete, or admin behavior.
  • GitHub has one active access profile today: oauth-app-write-capable. Because there is only one implemented profile, the UI should not show a GitHub access-profile selector.
  • Future GitHub App installation auth is planned for selected-repository, private-repository read-only access. When both OAuth App and GitHub App profiles exist, switching profiles must run the appropriate OAuth or installation flow; it is not a silent settings toggle.
  • Optional repository selection is shared connector resource-selection behavior. If no repository selection is configured, live queries use bounded searches across accessible repositories and must disclose sampled or incomplete coverage.
  • GitHub code search is provider-bounded keyword/code search, not semantic whole-codebase recall. Bounded file reads are transient grounding only and must not be stored.
  • GitHub organization OAuth app policies can block access until an organization approves the app. Surface that through auth, scope, or repo-inaccessible fallback states rather than treating it as a generic no-result.
  • GitHub Enterprise Server, Discussions, Projects, Actions/check rollups, Releases, Packages, security alerts, and package data are out of scope until a separate provider/domain/eval pass accepts them.

Real-Provider Smoke

Section titled “Real-Provider Smoke”

The GitHub real-provider lane is opt-in and fixture-owned. It needs a linked Better Auth GitHub account id, with optional pins for repository, issue, pull request, and path checks.

  • REAL_PROVIDER_E2E_GITHUB_ACCOUNT_ID=<github-linked-account-id>
  • optional REAL_PROVIDER_E2E_GITHUB_REPOSITORY_FULL_NAME=<owner/repo>
  • optional REAL_PROVIDER_E2E_GITHUB_QUERY=<query-text>
  • optional REAL_PROVIDER_E2E_GITHUB_EXPECTED_REPOSITORY_FULL_NAME=<owner/repo>
  • optional REAL_PROVIDER_E2E_GITHUB_EXPECTED_ISSUE_NUMBER=<number>
  • optional REAL_PROVIDER_E2E_GITHUB_EXPECTED_PULL_NUMBER=<number>
  • optional REAL_PROVIDER_E2E_GITHUB_EXPECTED_PATH=<repo-path>

Canonical Sources

Section titled “Canonical Sources”
  • packages/domain/src/connectors/connectorRegistry.ts
  • apps/auth/src/auth.ts
  • apps/auth/src/oauthProviders.ts
  • apps/api/src/connectors/githubApiClient.ts
  • apps/api/src/connectors/providerManifests.ts
  • apps/api/src/connectors/liveAccessCodeRepositoryContracts.ts
  • apps/api/src/mastra/tools/githubCodeRepositoryLiveQuery.ts
  • apps/api/src/mastra/tools/githubWorkItemLiveQuery.ts
  • docs/features/connectors/spec.md
  • docs/features/live-query/spec.md

Official Docs

Section titled “Official Docs”