GitHub Issues
Use issue numbers as IDs, keep pull requests out of issue results, and treat open or closed as GitHub's portable state boundary.
Configure
import { createWorkClient } from "work-sdk";
import { github } from "work-sdk/github";
export const work = createWorkClient({
adapter: github({
owner: "octo-org",
repo: "product",
token: process.env.GITHUB_TOKEN!,
}),
});The token stays in your process and requests go directly to api.github.com. Inject fetch in tests or when your runtime requires a custom transport.
Permissions
Fine-grained personal access tokens need repository access plus read and write permission for Issues. GitHub App installation tokens are preferable for multi-tenant applications because each installation has an explicit repository boundary.
Never expose a GitHub token to a browser or to an untrusted model prompt. Keep the Work SDK client in a server process or isolated tool runtime.
Identifiers
idThe decimal issue number as a string, for example "481".identifierA readable repository-qualified value such as octo-org/product#481.revisionA deterministic readback fingerprint used for preflight conflict detection.Field mapping
| Work SDK | GitHub | Notes |
|---|---|---|
| state | open / closed | Completed maps to closed; custom workflow states are not available. |
| assigneeIds | logins | Multiple assignees are supported when the repository allows them. |
| labels | label names | Unknown labels are rejected instead of silently created. |
| kind | issue | Pull requests are excluded from list results. |
Safe write
const change = await work.prepareUpdate("481", {
state: "completed",
labels: ["ready-to-ship"],
});
for (const warning of change.warnings) {
console.warn(warning.code, warning.message);
}
const result = await work.commit(change, {
idempotencyKey: "release:product#481",
acceptWarnings: change.warnings.length > 0,
});The returned receipt is narrowed to UpdateCommitResult. GitHub cannot atomically test an issue revision during the write, so update concurrency is reported as preflight, not atomic.
Limits and escape hatches
- GitHub Projects fields are outside the portable issue contract.
- Issue types and organization-specific metadata remain available through
rawfor reads. - Repository rules and token permissions can reject an action even when the adapter capability is true.