GraphQL Proxy

POST /api/github/graphql is a restricted relay to the GitHub GraphQL API. It uses the user OAuth token and only accepts a fixed set of named operations — you can’t send arbitrary queries through it.

Request contract

POST /api/github/graphql
Authorization: via gh_session cookie or Bearer header

{
  "operationName": "ViewerProfile",   // REQUIRED — must be in allowlist
  "query": "...",                      // optional — server may substitute its own
  "variables": {}                      // optional
}

The allowlist

Exactly 7 operations are exposed (USER_GITHUB_GRAPHQL_OPERATIONS in lib/github/operations/registry.ts):

Sending any other operationName returns 400.

Query resolution

The registry holds a OPERATION_QUERY_FALLBACKS map with server-owned query text for each operation. Resolution order:

1. If a server fallback exists for the operation → use it (client-supplied query is discarded)
2. If no fallback exists → use client-supplied query text
3. If neither exists → 400

In practice, the server always has fallbacks for the 8 allowed operations. The client’s query field is never used — the server’s version wins. This prevents the proxy from being abused for arbitrary field enumeration or introspection.

Authentication

The proxy uses the user OAuth token from the session, not an installation token:

getRequestSession() → decrypt token → createUserOctokit(accessToken) → octokit.graphql()

Server-side ingest queries in lib/github/fetch-graphql.ts run with installation tokens and bypass the proxy entirely. They are not constrained by the 8-operation allowlist.

Caching

The proxy has its own dedicated cache layer (lib/github/graphql-response-cache.ts):

OrgRepositories has a longer TTL because repository lists change infrequently. Cache hits skip the GitHub API call entirely, reducing rate limit pressure for frequent queries like org member searches.

Error responses

Adding a new operation

1. Add the name to USER_GITHUB_GRAPHQL_OPERATIONS in lib/github/operations/registry.ts
2. Write the GraphQL query string and add it to OPERATION_QUERY_FALLBACKS
3. Create a frontend hook in hooks/queries/ that calls the proxy
4. Add a query key in hooks/query-keys.ts

The proxy handler and executeGithubGraphql() don’t need changes — they’re driven entirely by the registry.

Server-only queries

The ingest pipeline uses additional queries that live in lib/github/queries/ and are called directly from lib/github/fetch-graphql.ts. These use installation tokens and are never exposed through the proxy. They include:

• repoScoringDataCore — commit data for scoring
• repoScoringDataPrMeta — PR metadata (merge status, linked issues)
• repoScoringDataReviews — review data with states
• repoScoringDataIssueLinks — issue-to-PR relationships

These queries handle pagination, enrichment (PR metadata, issue links, review details), and error handling that the public proxy doesn’t need to expose.