AGENT SKILL

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

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 both params and the returned data from the route string alone — never invent an operation: string wrapper, 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. RestRoute covers every documented route; RestPaginatingRoute is the narrower set client.paginate actually accepts, so a non-paginating route handed to it is rejected before the request is ever built. See references/pagination-retry-errors.md for the full type-level surface (RestParams, RestData, RestExtras).
  • requestDecoded is 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 Repo per call, not once at construction. The client is stable and built once; which repository a call targets is the caller's decision, and Repo.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.rateLimit and pace yourself if you need to.
  • Catch on GitHubError.kind, never a resource-specific tag. One taxonomy, classified once by GitHubError'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.upsert over a hand-rolled exists-then-create dance. The library already resolves the alreadyExists race with a create-then-reset recovery; a caller catching alreadyExists itself is redoing work the library did for it.
  • Forward PageOptions on every paginating call; never hard-code {}. perPage validates 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 layer factory in an arrow. Layer.effect(this, Effect.map(GitHubClient, (c) => make(c))) — passing make directly 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, BotIdentity and RepoRef reach nothing but effect; construct and test them directly, and don't wrap one in a Context.Service just 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's Exit, so assert with Exit/Cause.hasDies on the run, never with assert.throws around 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 octokit fetch-hook harness that exercises the real client end to end belongs to testing-actions.

REST calendar versioning

Verified against the live API:

  • The client pins x-github-api-version: 2026-03-10 on 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 a GitHubClientOptions.apiVersion (and GitHubAppOptions.apiVersion) option, which must be YYYY-MM-DD (anything else dies at construction). A GitHub Enterprise Server older than the default rejects it, so a client pointed at one must set apiVersion to the newest version that server supports. The resolved value is client.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 and data come 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_sha on a pull request, has_downloads on a repository — that is undefined at 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. Attestation pins its own version per call through the typed headers extra (RestExtras, see references/pagination-retry-errors.md), and a client pinned elsewhere leaves it alone.
  • On the old default, GitHub adds Deprecation/Sunset/Link headers only on endpoints the new version CHANGED, and octokit prints a warning for each that cannot be silenced (its fetch wrapper logs via request.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 optionalKey decodes the absence clean. 2026-03-10 removed merge_commit_sha from pull request objects, so PullRequestInfo.mergeCommitSha is read from GraphQL mergeCommit.oid instead, absent until the pull request merges (never the speculative test-merge sha). get, update and upsert always fill it; list and listAssociatedWithCommit leave it absent unless called with mergeCommits: true, which costs one GraphQL call per 100 merged pull requests. All five carry GitHubGraphQLError in their error channel. Before projecting a new field off a REST response, check GitHub's breaking-change list for the pinned version.

Footguns

  • GitTag.latestSemver picks the highest parsed version, not the most recently created tag — in a monorepo with independently-versioned packages the two disagree; scope with prefix to the package you mean. See references/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. See references/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.
  • GitCommit and GitHubCommit are easy to confuse: writing a commit onto a tree is GitCommit (Git Database API, no subprocess); reading what a commit says is GitHubCommit (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 full GitHubError/GitHubGraphQLError classification 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

spencerbeggs
spencerbeggs/effected

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.

★ 8
spencerbeggs
spencerbeggs/effected

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.

★ 8
spencerbeggs
spencerbeggs/effected

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.

★ 8
spencerbeggs
spencerbeggs/effected

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.

★ 8
spencerbeggs
spencerbeggs/effected

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.

★ 8
spencerbeggs
spencerbeggs/effected

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.

★ 8