fix(connectors): reuse the GitHub App OAuth client for the github connector

Merged
HA
2mo ago
+1-30

Summary

  • Point the github connector's requires_env at GH_APP_CLIENT_ID / GH_APP_CLIENT_SECRET instead of PLUGIN_GITHUB_CLIENT_ID / PLUGIN_GITHUB_CLIENT_SECRET.
  • Drop the now-unused PLUGIN_GITHUB_* pair from both env templates and both deploy workflows.

Why / Context

Connecting the GitHub plugin fails in production. The github connector declares:

"requires_env": ["PLUGIN_GITHUB_CLIENT_ID", "PLUGIN_GITHUB_CLIENT_SECRET"],

and connectorEnv() (packages/trpc/src/lib/connectors/index.ts:71) throws on any falsy value:

Connector "github" needs PLUGIN_GITHUB_CLIENT_ID, PLUGIN_GITHUB_CLIENT_SECRET, which are unset.

Neither secret has ever existed. There are zero PLUGIN_* secrets in superset-sh/superset — not repo-level (88 secrets), not in the Production environment (62), not in Preview. The api Vercel project holds only GITHUB_TOKEN and YC_DEALS_WEBHOOK_SECRET. Both workflows wired the pair correctly (env: block and --env flag), so they faithfully passed empty strings through.

This went unnoticed because neither name appears in any env schema — packages/trpc/src/env.ts declares only PLUGIN_CLIENT_METADATA_BASE_URL, and as .optional(). The API boots clean and fails only when a user clicks Connect, which is exactly the silent-failure mode docs/environment-variables.md step 2 warns about.

GH_APP_CLIENT_ID / GH_APP_CLIENT_SECRET are already real repo secrets, already in the env schema, already in both templates with fake local values, and already passed to the API by both deploy workflows. Reusing them fixes the connector with no new secret and no new plumbing.

How It Works

clientCredentials() derives the secret's name from the id's, so the rename needs no code change:

const idName = method.requires_env.find((n) => n.endsWith("_CLIENT_ID"));
const secretName = idName.replace(/_CLIENT_ID$/, "_CLIENT_SECRET");

GH_APP_CLIENT_ID → GH_APP_CLIENT_SECRET, both resolved from process.env.

The env-var checklist in docs/environment-variables.md is satisfied in both directions: the removed pair is gone from all five places (it only ever reached places 3 and 5), and the newly-referenced pair is already present in all five.

⚠️ Required manual step before this works

The GitHub App must list the connector callback URL. Add

https://api.boid.so/api/connectors/callback/github

to the Superset GitHub App's callback URLs (Apps support up to 10). Without it the redirect fails with The redirect_uri MUST match the registered callback URL. This PR cannot do that — it is a GitHub App setting.

Production also needs a redeploy after merge to pick up the changed connectors.json.

Known Limitations

  • GitHub Apps ignore the scope parameter. The connector still declares "scopes": ["repo", "read:org", "workflow"], but a GitHub App's user-authorization flow derives access from the App's configured permissions and its installations, not from classic OAuth scopes. So that scopes array becomes dead config, and the resulting user token can only reach repositories where the Superset App is installed — narrower than a classic OAuth app would grant. If the GitHub plugin's MCP server (https://api.githubcopilot.com/mcp/) needs broader reach, the right fix is a dedicated OAuth app plus setting the PLUGIN_GITHUB_* secrets, i.e. reverting this PR. I left scopes in place rather than deleting it, to keep that revert clean.
  • GitHub App user tokens expire (8 hours) when token expiration is enabled on the App. refresh.ts handles the refresh grant against the same token_url, but this path has not been exercised in production.
  • GH_APP_CLIENT_ID stays .optional() in the schema. That matches SENTRY_CLIENT_ID and MICROSOFT_CLIENT_ID, and MissingConnectorEnvError already gives a clear failure, so I did not promote it to required.

Testing

  • bun run lint — clean (8828 files)
  • bunx turbo typecheck --filter=@superset/shared --filter=@superset/trpc — 3/3 successful
  • bun test packages/shared/src/connectors packages/trpc/src/lib/connectors — 44 pass, 0 fail (includes the registry-schema validation of connectors.json)
  • bun run check:plugins — "All plugins are valid and published"

Not verified: the OAuth flow end to end. That needs the callback URL registered on the GitHub App and a production deploy, neither of which I can do from here. I also did not run a YAML linter (actionlint is not installed); the workflow edits are four two-line deletions from the middle of flat lists, and the --env shell continuation chain stays intact on both sides of each deletion.

Manual QA Checklist

  • Callback URL added to the GitHub App
  • Production redeployed
  • Plugins → GitHub → Connect completes the OAuth round trip
  • The connection lists the expected account under the right identity ($.login)
  • A GitHub plugin tool call succeeds against a repo where the App is installed
  • A repo where the App is not installed fails in a legible way rather than hanging
  • Preview deploy: confirm whether the App's callback list needs the preview origin too

Risks / Rollout

  • Risk: low blast radius — the connector is already 100% broken, so the worst case is that it stays broken in a different way. No other consumer reads PLUGIN_GITHUB_*. The GitHub App's existing sign-in and repo-integration flows are untouched; this only adds a second consumer of the same client credentials.
  • Rollout: merge → add the callback URL → redeploy production → connect once to verify.
  • Rollback: revert the commit and redeploy. If the App-permissions model proves too narrow (see Known Limitations), the forward fix is a dedicated GitHub OAuth app with PLUGIN_GITHUB_* set as secrets — the revert restores exactly that wiring.

Summary by cubic

Fixes the GitHub connector, which threw MissingConnectorEnvError on every connect because PLUGIN_GITHUB_CLIENT_ID and PLUGIN_GITHUB_CLIENT_SECRET were never set as repository secrets. The connector now reuses the existing GH_APP_CLIENT_ID / GH_APP_CLIENT_SECRET pair, and the unused PLUGIN_GITHUB_* pair is dropped from the env templates and both deploy workflows.

Required before this works

  • Register https://api.boid.so/api/connectors/callback/github as a callback URL on the Superset GitHub App, then redeploy production.

Known limitations

  • GitHub Apps ignore the scope parameter, so the declared scopes are dead config and access is limited to repos where the App is installed.
  • GitHub App user tokens expire after 8 hours; the refresh path exists but hasn't been exercised in production.

Summary by CodeRabbit

  • Updates
    • GitHub connector authentication now uses GitHub App credentials instead of the previous connector-specific credentials.