Skip to content
← Public packages

@kody/github

Call GitHub REST, GraphQL, and pull requests with a GitHub OAuth App or a personal access token.

FollowFork
Featured

IntegrationsTopics: github, api, oauth, pat, pr, automation

Version
1.0.0
License
MIT
Published
November 15, 2026
Pinned commit
793e731
Rating
★ 4.8 (5)
Forks
0
Adaptation effort
1.4

README

Agent docs

@kody/github

Intent

Reusable GitHub REST, GraphQL, and pull request helpers for Kody agents. Every helper reads one credential slot named github, which a personal access token or a GitHub OAuth connection can fill. The caller picks which credential fills it with the execute credentials map. There are no hard-coded personal aliases and no auth parameters on the calls.

What it does

  • Call the GitHub REST and GraphQL APIs with the credential the run picked
  • Verify which GitHub identity will perform an action
  • Fetch pull request details and the CI verdict (status check rollup) with the checks the token can read
  • Preview or apply PR merges and draft/ready status (dryRun / confirm)

Prerequisites / setup

Save a GitHub personal access token or connect a GitHub OAuth App before calling helpers. If a GitHub credential already exists, reuse it. Never paste tokens into chat. Agents: see AGENTS.md for import paths and smoke checks.

Pick the credential

The package declares one need in kody.credentials: github, with no kind, so a Key (PAT) or an OAuth connection with provider github can fill it. Kody resolves it in this order:

  1. The caller's credentials map for this run: { credentials: { github: "githubAccessToken" } } on execute, or --credential github=githubAccessToken with the CLI.
  2. A stored mapping for the trigger that started the run.
  3. Your default mapping for the entry package, then the org's default.
  4. The one credential you can use that matches provider github.

With two or more GitHub credentials and no map or default, the call fails with credential_ambiguous and lists the options. A package that imports @kody/github from a job or webhook should have a default mapping for its github need (the entry package's Credentials tab).

Lanes

LaneCredentialWhen to use
A. Personal access tokenKey credential with provider githubFastest for many automations; fine-grained tokens for read-only private-repo access.
B. Bring-your-own OAuth AppOAuth connection with provider githubDurable OAuth with your own client and rate limits.

This is not a GitHub App / installation-token package. Required hosts: api.github.com, uploads.github.com.

Lane A: personal access token

  1. Open github.com/settings/personal-access-tokens and generate a fine-grained token (classic tokens at github.com/settings/tokens also work but are coarser).
  2. Set an expiration, choose repositories, and pick the minimum permissions (for reporting: Contents: Read-only and Pull requests: Read-only; add write only for mutations). Fine-grained tokens have no Checks permission: pr/get-checks still returns the CI verdict, names commit statuses, and counts check runs it cannot read in unreadableCount. Name GitHub Actions jobs with Actions: Read-only (/actions/runs?head_sha={sha}, then each run's /jobs), or use a classic token with repo (also grants write) or a GitHub App with Checks: Read-only to name every check run.
  3. Copy the token once. Never paste it into chat.
  4. Save it in Kody with provider github (replace <org> with your org slug):
https://kody.codes/@<org>/-/credentials/new?kind=secret&name=githubAccessToken&provider=github&description=GitHub%20fine-grained%20personal%20access%20token&allowedHosts=api.github.com%2Cuploads.github.com

An existing Key without a provider matches once its provider is set to github (on its credential page, or credentialUpdate).

Lane B: bring-your-own OAuth App

  1. Open github.com/settings/developers, then OAuth Apps, then New OAuth App.
  2. Set the Authorization callback URL exactly to https://kody.codes/connect/oauth.
  3. Generate a client secret. GitHub still requires the client secret at the token endpoint even with PKCE, so the Kody flow is confidential.
  4. Connect (adjust scopes as needed; add &org=<team-slug> for a team org):
https://kody.codes/connect/oauth?provider=github&authorizeUrl=https%3A%2F%2Fgithub.com%2Flogin%2Foauth%2Fauthorize&tokenUrl=https%3A%2F%2Fgithub.com%2Flogin%2Foauth%2Faccess_token&flow=confidential&scopes=read%3Auser%20repo%20user%3Aemail&allowedHosts=api.github.com%2Cuploads.github.com

Decoded: authorize https://github.com/login/oauth/authorize, token https://github.com/login/oauth/access_token, flow=confidential, scopes read:user repo user:email, hosts api.github.com,uploads.github.com. Add pkce=true to layer S256 PKCE on the confidential exchange.

Suggested BYO scope tiers (space-delimited):

  • Read-mostly public: read:user, user:email, notifications, public_repo, read:org
  • Private repos: repo (write comes with it), plus gist / workflow only if needed

Multiple GitHub identities

Save each identity as its own credential with provider github (for example githubAccessToken and github-work), then pick one per run with the credentials map, or set a default mapping per package or trigger.

Upgrading from 0.x

1.0.0 removed the secretName, integrationName, and account options. Passing any of them throws an error that names the credentials map. Replace getViewer({ secretName: 'githubAccessToken' }) with getViewer() plus --credential github=githubAccessToken (or credentials: { github: 'githubAccessToken' } on execute). response.auth now describes the credential that was used ({ credentialKey, name, scope, kind, label }) and is null on dry-run previews.

Mutations

pr/merge, pr/set-review-status, GraphQL mutation operations, and REST methods other than GET / HEAD / OPTIONS require dryRun: true (preview) or confirm: true (live write).

Done when

  • A GitHub PAT or OAuth connection with provider github exists and the GitHub hosts are approved
  • get-viewer returns a login for the picked credential
  • Mutations refuse to write GitHub unless dryRun: true or confirm: true
Report this listing

Log in to report this listing.