@kody/github

@kody/github

Intent

Reusable GitHub REST, GraphQL, and pull request helpers for Kody agents. One package covers a GitHub OAuth App you register and personal access tokens. Multi-account routing is an integrationName (OAuth) or secretName (PAT) parameter — there are no hard-coded personal aliases.

What it does

• Call the GitHub REST and GraphQL APIs with the correct saved credential
• Verify which GitHub identity will perform an action
• Fetch pull request details and CI check-runs
• Preview or apply PR merges and draft/ready status (dryRun / confirm)

Prerequisites / setup

Create a GitHub OAuth App (or save a PAT) before calling helpers. If a github connection already exists, reuse it. Never paste tokens into chat. Agents: see AGENTS.md for import paths and smoke checks.

Auth lanes

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).
3. Copy the token once. Never paste it into chat.
4. Save it in Kody and approve the hosts:

https://kody.codes/account/secrets/new?name=githubAccessToken&description=GitHub%20fine-grained%20personal%20access%20token&allowedHosts=api.github.com%2Cuploads.github.com&scope=user

5. Call helpers with secretName: 'githubAccessToken' (or your chosen name). secretName selects the PAT lane and ignores integrationName.

Lane B: bring-your-own OAuth App

1. Open github.com/settings/developers → OAuth Apps → 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 provider and scopes as needed):

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

Every export accepts optional integrationName (OAuth, default github) and secretName (PAT). Connect extra accounts under their own integration names — for example github-work — by changing provider in the connect URL. Pass that name on every call. Do not hard-code personal aliases in forks of this package.

account is accepted as an alias for integrationName. The retired alias bot throws with the connect and PAT setup URLs above.

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

• OAuth integration github is connected and/or secret githubAccessToken is saved with GitHub hosts approved
• Identity check returns a login for the selected lane
• Mutations refuse to write GitHub unless dryRun: true or confirm: true