github-api
Use when calling GitHub's REST or GraphQL API from Effect v4 code through @effected/github — typing a client.request call by route, choosing paginate vs paginateStream, building a GitBranch or GitTag upsert, classifying or catching a GitHubError, or wiring a resource service's layer.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 8
- Forks
- 2
01 前言 Front Matter
- name
- github-api
- description
- Use when calling GitHub's REST or GraphQL API from Effect v4 code through @effected/github — typing a client.request call by route, choosing paginate vs paginateStream, building a GitBranch or GitTag upsert, classifying or catching a GitHubError, or wiring a resource service's layer.
- when_to_use
- client.request, requestDecoded, GitHubError, Repo, RetryPolicy, GraphQLDocument, TokenPermissions, CheckRunOutput, CommentMarker, GitBranch upsert, GitTag upsert, GitHub REST API, GitHub GraphQL API
02 资源文件 2
- 参考文档references/pagination-retry-errors.md11.3 KB
- 参考文档references/resources.md20.3 KB
03 SKILL.md 正文
@effected/github: calling GitHub from Effect v4
Typed GitHub REST and GraphQL over @octokit/core's request surface, plus
the resource services (GitBranch, PullRequest, GitHubIssue, …) that
turn raw endpoints into domain operations. General Effect v4 rules — service
shapes, layer composition, memoization, Schema.Class, testing idioms —
live in effect-v4-services-layers, effect-v4-schema, effect-v4-idioms,
effect-v4-testing; this skill states only what @effected/github does
differently or as a worked instance.
What you have
| Construct | Import | Reach for it when |
|---|---|---|
GitHubClient (.request, .requestDecoded, .paginate, .paginateStream, .graphql, .rateLimit) |
import { GitHubClient } from "@effected/github" |
Calling any REST or GraphQL endpoint directly |
Repo |
@effected/github |
Scoping a program to an owner/repo pair, or targeting a second repo mid-program |
RetryPolicy |
@effected/github |
Configuring the client's one retry/backoff policy |
GitHubError, GitHubGraphQLError |
@effected/github |
Classifying or catching a REST/GraphQL failure |
GraphQLDocument |
@effected/github |
Building a typed GraphQL query or mutation |
GitBranch, GitTag, GitCommit |
@effected/github |
Writing branches, tags, commits and trees through the Git Database API |
GitHubCommit |
@effected/github |
Reading commits as GitHub reports them (not the Git Database API) |
GitHubRepository, GitHubContent |
@effected/github |
Repo settings/default branch, or reading a file at a ref |
GitHubIssue, PullRequest, PullRequestComment |
@effected/github |
Issues, PRs, and sticky PR/issue comments |
CheckRun, WorkflowDispatch |
@effected/github |
Check runs, and dispatching/polling another workflow |
Attestation, ArtifactMetadata |
@effected/github |
Uploading a signed attestation; artifact storage-record bookkeeping |
TokenPermissions, CheckRunOutput, CommentMarker, BotIdentity, RepoRef |
@effected/github |
Pure classes — no layer, no service, testable standalone |
Full per-resource member signatures live in
references/resources.md — this table is the
routing index, not the catalogue.
Standards
- Route through the literal.
client.request(route, params)types bothparamsand the returned data from the route string alone — never invent anoperation: stringwrapper, a callback, or a cast; a cast in route-typed code is a defect, not a shortcut. - Let the route decide what's paginatable, at compile time.
RestRoutecovers every documented route;RestPaginatingRouteis the narrower setclient.paginateactually accepts, so a non-paginating route handed to it is rejected before the request is ever built. Seereferences/pagination-retry-errors.mdfor the full type-level surface (RestParams,RestData,RestExtras). requestDecodedis an escape hatch from the route table, never from typing. Reach for it only when a route is absent from GitHub's OpenAPI map or its live shape diverges, and always pass the schema — a shape mismatch then fails typed (kind: "decode") instead of trusting an unchecked value.- Resolve
Repoper call, not once at construction. The client is stable and built once; which repository a call targets is the caller's decision, andRepo.provide(other)must actually change it. - One retry policy, wired at the client layer. Every resource inherits
it; never give a resource its own retry logic, and never build a
proactive rate limiter — read
client.rateLimitand pace yourself if you need to. - Catch on
GitHubError.kind, never a resource-specific tag. One taxonomy, classified once byGitHubError's shared classifier (fromOctokit/fromResponse) — a resource-specific error class has no successor to catch, and a real survey of consumers found a resource-specific tag matched almost never. - Prefer
GitBranch.upsert/GitTag.upsertover a hand-rolled exists-then-create dance. The library already resolves thealreadyExistsrace with acreate-then-reset recovery; a caller catchingalreadyExistsitself is redoing work the library did for it. - Forward
PageOptionson every paginating call; never hard-code{}.perPagevalidates rather than clamps, so a caller asking for more than 100 per page has a bug worth failing on at the boundary, not discovering in production. - Wrap a resource's
layerfactory in an arrow.Layer.effect(this, Effect.map(GitHubClient, (c) => make(c)))— passingmakedirectly throws at import time from the static initializer, not at layer-build time; every resource in the package follows this shape identically. - Pure classes need no layer.
TokenPermissions,CheckRunOutput,CommentMarker,BotIdentityandRepoRefreach nothing buteffect; construct and test them directly, and don't wrap one in aContext.Servicejust to gain a double — there is nothing to mock. - Every resource ships
makeTest/layerTest. Every unstubbed member dies when run, naming itself: calling it only builds the effect, and the defect is in that effect'sExit, so assert withExit/Cause.hasDieson the run, never withassert.throwsaround the call. A value member (GitHubRepository.settings) is the dying effect itself and the double still builds without it. Build a partial double from the member table, not from a stack trace. The octokitfetch-hook harness that exercises the real client end to end belongs totesting-actions.
REST calendar versioning
Verified against the live API:
- The client pins
x-github-api-version: 2026-03-10on every request. octokit itself sends no header, and without one GitHub serves its oldest supported calendar version (2022-11-28, sunset 2028-03-10). The pin is aGitHubClientOptions.apiVersion(andGitHubAppOptions.apiVersion) option, which must beYYYY-MM-DD(anything else dies at construction). A GitHub Enterprise Server older than the default rejects it, so a client pointed at one must setapiVersionto the newest version that server supports. The resolved value isclient.apiVersion; calendar versions compare correctly as strings (client.apiVersion < "2026-03-10"). - The route types describe a different version than the one the client
sends.
client.request's params anddatacome from octokit's generated types, which describe GitHub's oldest supported api-version, not the default the client pins. So a route type can claim a field —merge_commit_shaon a pull request,has_downloadson a repository — that isundefinedat runtime. Treat a field the pinned version removed as absent whatever the type says, and check the version's breaking-change list before reading a new one. - A per-call header wins over the option.
Attestationpins its own version per call through the typedheadersextra (RestExtras, seereferences/pagination-retry-errors.md), and a client pinned elsewhere leaves it alone. - On the old default, GitHub adds
Deprecation/Sunset/Linkheaders only on endpoints the new version CHANGED, and octokit prints a warning for each that cannot be silenced (its fetch wrapper logs viarequest.log ?? console). That warning means "this client is on an old calendar version", not "this route is deprecated"; the fix is the pin, never a logging knob. - A calendar-version change REMOVES response fields, and an
optionalKeydecodes the absence clean.2026-03-10removedmerge_commit_shafrom pull request objects, soPullRequestInfo.mergeCommitShais read from GraphQLmergeCommit.oidinstead, absent until the pull request merges (never the speculative test-merge sha).get,updateandupsertalways fill it;listandlistAssociatedWithCommitleave it absent unless called withmergeCommits: true, which costs one GraphQL call per 100 merged pull requests. All five carryGitHubGraphQLErrorin their error channel. Before projecting a new field off a REST response, check GitHub's breaking-change list for the pinned version.
Footguns
GitTag.latestSemverpicks the highest parsed version, not the most recently created tag — in a monorepo with independently-versioned packages the two disagree; scope withprefixto the package you mean. Seereferences/resources.md.- A route absent from the generated paginating-route map (e.g.
GitHubCommit.changedFiles) needs its own page source — never a manual loop that reimplements pagination beside the one real engine. Seereferences/pagination-retry-errors.md. - A hand-written route (release-asset upload, attestation upload) owns its own query parameters in the URI template — a parameter passed only as an argument, never templated, gets silently dropped by octokit rather than rejected.
GitCommitandGitHubCommitare easy to confuse: writing a commit onto a tree isGitCommit(Git Database API, no subprocess); reading what a commit says isGitHubCommit(the higher-level commits API).
Out of scope — see the named skill
- GitHub App authentication, token lifecycle, client constructors →
github-app-tokens. - Check runs and PR comments as a reporting workflow (as opposed to the raw
member catalogue) →
actions-reporting. - The octokit
fetch-hook test harness →testing-actions. - Attestation upload as part of a sign/SBOM pipeline →
supply-chain-attestation.
Additional resources
- references/resources.md — the full per-resource member catalogue: every service's methods, signatures and return shapes. Load when: you need a specific method's signature or return type for any of the fourteen resource services.
- references/pagination-retry-errors.md —
the route-typing type-level surface (
RestParams,RestData,RestExtras,RestPaginatingRoute), the pagination engine's request-budget semantics, the retry/backoff schedule, and the fullGitHubError/GitHubGraphQLErrorclassification and GraphQL-document mechanics. Load when: typing a route by hand, tuning a paginating call, debugging a retry sequence, or classifying/catching a GitHub error.
04 同仓库更多 Skills
testing-actions
Use when writing or reviewing tests for @effected/github-actions, @effected/github, @effected/sbom or @effected/commands — stubbing the GitHub API, writing a service's layerTest or makeTest double, testing the pre/main/post lifecycle through Action.run, or debugging why a test hits the real network or hangs.
supply-chain-attestation
Use when generating a CycloneDX SBOM, checking NTIA minimum elements, building an in-toto statement or a SLSA provenance predicate, signing into a Sigstore DSSE bundle, or uploading an attestation to GitHub.
structuring-an-action
Use when laying out a new GitHub Action repository on the @effected suite, deciding where a piece of code belongs (an entry point, a step, a shared service, a shim), or reviewing an existing action's file structure against the canonical shape.
running-commands-and-tools
Use when running a subprocess in Effect v4, spawning a command, capturing stdout/stderr/exit code, checking whether a CLI tool is installed or which copy to run, running a package-manager script through the project's launcher, detaching a background process, or redacting a secret from argv or captured output.
release-and-publish
Use when publishing a package to npm, reading the npm registry from Effect v4, checking whether a version is already published, cutting a release tag or GitHub release from an action, applying a release-age gate, or deriving tracking tags for GitHub Actions distribution.
hardening-a-parser-port
Use when porting or writing a recursive-descent parser, lexer, or tree-walker over untrusted text in the @effected monorepo — the class of hardening the cloud reviewer scans for on every migration. Covers stack-overflow depth guards (on EVERY recursion surface, which a facade has N of — not two), numeric bound guards that must reject NaN and non-integers, code-point range checks scoped to formats with wide escapes, prototype-pollution, control-character rejection, and the invariant that malformed input must fail through the typed error channel, never as an unhandled defect.