@kody/github
Call GitHub REST, GraphQL, and pull requests with a GitHub OAuth App or a personal access token.
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:
- The caller's credentials map for this run:
{ credentials: { github: "githubAccessToken" } }onexecute, or--credential github=githubAccessTokenwith the CLI. - A stored mapping for the trigger that started the run.
- Your default mapping for the entry package, then the org's default.
- 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
| Lane | Credential | When to use |
|---|---|---|
| A. Personal access token | Key credential with provider github | Fastest for many automations; fine-grained tokens for read-only private-repo access. |
| B. Bring-your-own OAuth App | OAuth connection with provider github | Durable 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
- 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).
- 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-checksstill returns the CI verdict, names commit statuses, and counts check runs it cannot read inunreadableCount. Name GitHub Actions jobs with Actions: Read-only (/actions/runs?head_sha={sha}, then each run's/jobs), or use a classic token withrepo(also grants write) or a GitHub App with Checks: Read-only to name every check run. - Copy the token once. Never paste it into chat.
- 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.comAn 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
- Open github.com/settings/developers, then OAuth Apps, then New OAuth App.
- Set the Authorization callback URL exactly to
https://kody.codes/connect/oauth. - Generate a client secret. GitHub still requires the client secret at the token endpoint even with PKCE, so the Kody flow is
confidential. - Connect (adjust
scopesas 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.comDecoded: 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), plusgist/workflowonly 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
githubexists and the GitHub hosts are approved get-viewerreturns aloginfor the picked credential- Mutations refuse to write GitHub unless
dryRun: trueorconfirm: true
Report this listing
Log in to report this listing.