plugin-github

Imported from gabrielmoreira/agent-skills-mirror (mirrors/repos/elizaOS@eliza/plugins/plugin-github/AGENTS.md). Install upstream with npx skills add gabrielmoreira/agent-skills-mirror --skill plugin-github. Copyright stays with the author.

@elizaos/plugin-github

GitHub integration for Eliza agents: pull request listing and review, issue lifecycle management, and notification triage via the GitHub REST API.

Purpose / role

Adds GitHub capabilities to any Eliza agent. The plugin is opt-in — add "@elizaos/plugin-github" to the agent's plugin list. It registers a GitHubService (Octokit REST client pool), three exposed action handlers promoted under one umbrella GITHUB action, five API routes for credential management (PAT paste + OAuth device sign-in — the guided setup step behind the Settings → Coding Agents GitHub card, #15796), and a search category for PR lookup.

Plugin surface

Actions (registered via promoteSubactionsToActions(githubAction))

The umbrella action GITHUB dispatches to three sub-actions based on the action parameter:

All actions gate on contextGate: { anyOf: ["code", "tasks", "connectors", "automation"] } and roleGate: { minRole: "USER" }.

Services

Routes

Registered at plugin init on the agent's HTTP server:

Search category

github_pull_requests — registered at init via registerGitHubSearchCategory. Filters: query, repo, state, author, as, accountId, limit. Contexts: code, automation.

Connector account provider

Registers with ConnectorAccountManager at init to expose GitHub accounts (PAT and OAuth) through the generic connector CRUD + OAuth flow surfaces. OAuth requires GITHUB_OAUTH_CLIENT_ID, GITHUB_OAUTH_CLIENT_SECRET, GITHUB_OAUTH_REDIRECT_URI; authorization codes are bound to one-time S256 PKCE verifiers and exchanged under a finite request deadline.

Layout

src/
  index.ts                     Plugin export, route wiring, plugin object
  register-routes.ts           App-route plugin loader — registers githubPlugin via registerAppRoutePluginLoader
  types.ts                     GitHubIdentity, GitHubOctokitClient, GitHubActions, result types
  accounts.ts                  Account config reading (env + character settings + connector store)
  action-helpers.ts            Shared: service lookup, client resolution, param helpers
  rate-limit.ts                Rate-limit detection and formatting
  github-credentials.ts        Local PAT store: load/save/clear at <state-dir>/credentials/github.json
  device-flow.ts               GitHub OAuth device-flow state machine (start/poll; per-agent scoped; device_code stays server-side)
  search-category.ts           github_pull_requests search category registration
  connector-account-provider.ts  ConnectorAccountManager bridge (PAT + OAuth flows)
  connector-credential-refs.ts   Credential ref persistence helpers
  actions/
    github.ts                  GITHUB umbrella action — dispatches by action= param
    issue-op.ts                GITHUB_ISSUE action (create/assign/close/reopen/comment/label)
    pr-op.ts                   GITHUB_PR action (list/review)
    notification-triage.ts     GITHUB_NOTIFICATION_TRIAGE action + scoreNotification export
  services/
    github-service.ts          GitHubService — Octokit client pool, account resolution
  routes/
    github-routes.ts           Pure handleGitHubRoutes dispatcher for PAT CRUD endpoints

Commands

bun run --cwd plugins/plugin-github build       # tsup ESM build + .d.ts
bun run --cwd plugins/plugin-github test        # vitest run
bun run --cwd plugins/plugin-github typecheck   # tsc --noEmit
bun run --cwd plugins/plugin-github clean       # rm dist .turbo

Config / env vars

At least one account source — GITHUB_ACCOUNTS, GITHUB_USER_PAT, GITHUB_AGENT_PAT, or a character.settings.github.accounts entry — must be set for the plugin's actions to resolve a client. A bare GITHUB_TOKEN is not itself an account source: it bootstraps gh/git subprocess auth (and takes precedence over any locally saved credential) but does not register a user/agent account on its own. A missing user or agent account causes that role's operations to be rejected at runtime (logged as [GitHubService] no GitHub <role> account configured).

Character-level config is also supported under character.settings.github.accounts (array or object keyed by account ID).

How to extend

Add a new action:

1. Create src/actions/my-op.ts exporting a typed Action with name, contexts, contextGate, roleGate, validate, and handler.
2. Use buildResolvedClient(runtime, selection) from action-helpers.ts to get an authenticated Octokit client.
3. Call requireConfirmation from @elizaos/core for any write op.
4. Register the new action in src/actions/github.ts by extending GITHUB_ACTIONS and adding a dispatch branch in the umbrella handler, OR add it directly to the actions array in src/index.ts.

Add a new provider/evaluator: Export from src/index.ts and add to the githubPlugin object's providers or evaluators arrays.

Add a new route: Add an entry to githubRoutes in src/index.ts and a handler in src/routes/github-routes.ts. Routes use raw http.IncomingMessage / http.ServerResponse — no Express.

Conventions / gotchas

• Confirmation is not optional for write ops. All write actions use requireConfirmation from @elizaos/core. The confirmed: true parameter in the action schema is vestigial — the runtime confirmation gate is authoritative. isConfirmed in action-helpers.ts always returns false and is deprecated.
• Two identity roles, two PATs. user = human acting; agent = the Eliza agent acting. Operations that affect the repo on behalf of the agent use agent; operations that respond as the user (reviews, notifications) default to user.
• Account precedence: GITHUB_ACCOUNTS JSON > GITHUB_USER_PAT/GITHUB_AGENT_PAT legacy env vars. Character settings are layered in before env vars. ConnectorAccountManager credentials (OAuth) overlay everything by accountId.
• No test harness for route auth. handleGitHubRoutes is a pure dispatcher with no auth. The agent's server layer is expected to authenticate before calling the route handler.
• Rate limits surface cleanly. inspectRateLimit in rate-limit.ts detects GitHub rate-limit responses (HTTP 403 with x-ratelimit-remaining: 0); formatRateLimitMessage renders a human-readable message with the reset time from x-ratelimit-reset.
• PAT storage is local-first. <state-dir>/credentials/github.json (mode 0600). Written atomically via a tmp-rename. The token is never returned to the browser via the GET route.
• OAuth provider origins are pinned. Production token and user requests use the fixed GitHub endpoints. The exported contract-test factory is disabled outside NODE_ENV=test and rejects every non-loopback endpoint before credentials can be sent.
• GitHubOctokitClient is a structural interface, not the full Octokit class — tests can inject a mock without depending on the real Octokit.
• tsup builds two entry points: src/index.ts and src/register-routes.ts. register-routes.ts is an app-route plugin loader that calls registerAppRoutePluginLoader("@elizaos/plugin-github", ...) — it registers the full githubPlugin, it is not a route-only subset.

Verification

Follow the repository-wide verification and evidence standard in the root CLAUDE.md. Run the package's relevant build, typecheck, lint, and test commands, then exercise the real integration boundary changed by the work. Inspect the produced domain artifacts and failure behavior; do not substitute mocked success for the system under test.