@kentcdodds/github

@kentcdodds/github — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke checks, snippets, and edge cases. Secrets by name only — never paste token values. Do not disable live webhooks or jobs.

Auth / integrations

Auth uses createAuthenticatedFetch('<integration>') against the saved OAuth connection. Do not rely on mirrored user secrets like github-botAccessToken / github-kentAccessToken — those are not required and may be absent even when OAuth works.

Reconnect: /connect/oauth?provider=github-bot or /connect/oauth?provider=github-kent.

Import paths

Prefer static kody:@kentcdodds/github/... imports from execute. Do not lead with packages.invoke. If you must invoke dynamically, pass bare kody id github (not @kentcdodds/github).

Smoke test (read-only)

import getGithubViewer from 'kody:@kentcdodds/github/get-viewer'

export default async function main() {
	return await getGithubViewer({ account: 'bot' })
	// => { account: 'bot', login: 'kody-bot', id, type, ... }
}

Optional workflows reachability probe (creates a trivial workflow):

import probe from 'kody:@kentcdodds/github/pr/workflows-probe'

export default async function main() {
	return await probe({})
}

Common snippets

REST:

import githubRequest from 'kody:@kentcdodds/github/request'

export default async function main() {
	const response = await githubRequest({
		account: 'bot',
		path: '/repos/kentcdodds/kody',
		throwOnError: true,
	})
	return response.data
}

PR info:

import getPrInfo from 'kody:@kentcdodds/github/pr/get-info'

export default async function main() {
	return await getPrInfo({
		owner: 'kentcdodds',
		repo: 'kody',
		prNumber: 1,
		account: 'bot',
	})
}

Merge (caller does not need to retry slow merges):

import mergePr from 'kody:@kentcdodds/github/pr/merge'

export default async function main() {
	return await mergePr({
		prUrl: 'https://github.com/kentcdodds/kody/pull/969',
		mergeMethod: 'squash',
	})
	// Slow GitHub merge may return status: 'merge_dispatched' + workflowId.
}

Put Actions secret (plaintext never returned; prefer generateBytes when minting):

import putActionsSecret from 'kody:@kentcdodds/github/actions/put-secret'

export default async function main() {
	return await putActionsSecret({
		owner: 'kentcdodds',
		repo: 'kody',
		name: 'EXAMPLE_SECRET_NAME',
		generateBytes: 32,
	})
}

Edge cases

• Default account is always bot. Never switch to kent unless the user explicitly asks to act as Kent C. Dodds / kentcdodds.
• PR locators: { prUrl } or { owner, repo, prNumber } (number aliases prNumber). Optional account on all PR helpers.
• pr/merge bounds the direct attempt (timeoutMs default 25000), escalates to a durable workflow on abort, and stays under a ~55s call budget. Fail-fast for closed/draft/dirty/blocked/not-mergeable. Already-merged is idempotent. timed_out_unconfirmed only when workflows are unavailable.
• pr/merge-durable is the workflow entry — agents normally do not call it.
• pr/set-review-status: status: 'draft' | 'ready' | 'toggle'; mutation bounded by timeoutMs.
• request has no default timeout on ordinary reads; pass timeoutMs / signal for long-lived mutations that can hang.
• actions/put-secret: pass value or generateBytes (not both); never log or return the secret value.