@agentforge-io/connectors-github

GitHub connector for AgentForge. Adds an issues + PRs toolbelt (list repos / list & get & create issues / comment / list & create PRs / review comments) that any agent can use after the end user has authorized via OAuth2.

Companion design doc: GITHUB_CONNECTOR_SDD.md at the repo root.

Quickstart

1. Create the GitHub OAuth App at https://github.com/settings/developers → OAuth Apps → New OAuth App.

   • Authorization callback URL = https://<your-agentforge-host>/connectors/oauth/callback
   • Copy Client ID and generate a new Client Secret.

2. Register the connector in your host's bootstrap (or rely on the platform's vault-driven wiring — connectors.module.ts already does this if you set GITHUB_OAUTH_CLIENT_ID / GITHUB_OAUTH_CLIENT_SECRET in Settings → Secrets):

   import { githubConnector } from '@agentforge-io/connectors-github';
   
   connectorRegistry.register(githubConnector({
     clientId: env.GITHUB_OAUTH_CLIENT_ID,
     clientSecret: env.GITHUB_OAUTH_CLIENT_SECRET,
   }));

3. End-user clicks Connect on the GitHub card in /connectors, authorizes on GitHub's side, and lands back ready to use the tools.

Tools

Account-wide discovery (no owner/repo needed — covers EVERY repo the token can see):

| Name | Purpose | |---|---| | github_list_orgs | List orgs the user belongs to — resolves owner when it's not the personal login | | github_list_repos | Discover repos across personal + orgs to resolve owner/name | | github_list_my_issues | "What's on my plate?" — issues+PRs across every repo, no enumeration | | github_search_issues | Cross-repo search with GitHub's qualifier syntax (is:pr review-requested:@me, org:acme label:bug, etc.) | | github_search_commits | Cross-repo commit search (author:@me committer-date:>2026-05-21, org:acme repo:owner/name) |

Per-repo operations (need owner + repo — GitHub's REST surface is repo-scoped):

| Name | Purpose | |---|---| | github_list_issues | List issues in one repo (PRs filtered out) | | github_get_issue | Fetch one issue/PR with body + labels + assignees | | github_create_issue | Open an issue with title / body / labels / assignees | | github_comment_issue | Comment on an issue OR PR (same number namespace) | | github_list_pull_requests | List PRs (open / closed / all) with branch filters | | github_create_pull_request | Open a PR from an existing branch (does NOT push code) | | github_create_review_comment | Inline diff comment on a PR line/range | | github_list_pr_review_threads | List review threads on a PR (resolved vs open) — GraphQL | | github_resolve_review_thread | Mark a PR review thread as resolved / unresolved — GraphQL |

The discovery tools above feed owner + repo into the per-repo ones — the user is never bound to a single repo. A typical flow: list_my_issues to see what needs attention, then comment_issue to act on a specific one. For PR review: list_pr_review_threads to find unresolved threads, then resolve_review_thread to close them out.

REST vs GraphQL

The package is REST-first (zero deps, fetch wrapper). Two operations use GraphQL because they don't exist in REST v3: github_list_pr_review_threads and github_resolve_review_thread. Same bearer token, same retry policy — the wrapper just talks to /graphql instead of /<resource>.

Scopes

Default: repo, read:user, user:email. GitHub OAuth Apps don't support per-repo scoping (that's GitHub Apps) — repo is all-or-nothing across private repos. Override via githubConnector({ ..., scopes: [...] }) if you need public-only access (use ['public_repo', 'read:user']).

Adding a scope = every connected user must re-authorize. Treat scope additions as breaking changes for the package's semver.

Tokens

OAuth App tokens are long-lived; no refresh dance. They invalidate when:

• the user revokes the app from github.com/settings/applications,
• an org admin removes the OAuth App from the org's third-party access list,
• the token sits unused for >1 year (GitHub auto-expires).

On 401 the registry surfaces auth_required and the user reconnects from /connectors.

Common gotchas

• 404 on org repos. The OAuth App needs the org admin's approval at Settings → Third-party access. We surface GitHub's error verbatim so the model can ask the right next step.
• redirect_uri_mismatch during OAuth. The Authorization callback URL on the GitHub OAuth App must match /connectors/oauth/callback exactly, including https and no trailing slash. GitHub displays only the origin in its UI summary but stores the full path internally — that's cosmetic, not a problem with what you saved.
• head branch ... does not exist when creating a PR. The connector doesn't push code — the branch must already exist on the remote.