@shivaedev/github 0.8.6 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 0.10.0 - 2026-11-02
+
+### Added
+
+- Add typed, byte-capped issue, user, collaborator-permission, commit, comparison and tree reads, plus paged issue, pull-request-file and commit lists on the GitHub service.
+- Let Schema-aware lists select arrays inside envelopes, pace each request and opt into skipping undecodable items. `listPages` reports decoded items and skipped counts for each page; `listBounded` includes the total `skipped` count alongside `items` and `truncated`. Existing numeric byte-limit arguments remain supported, and decoding still fails by default.
+- `GitHubApp.viewerRepositories(account)` accepts a GitHub account ID or login and returns readable and administrable installed repositories, with access results cached for 60 seconds across at most 100 accounts.
+
+### Fixed
+
+- Preserve configured GitHub API path prefixes in representation reads, lists and writes, App installation discovery and token exchange, and artifact API requests. API origins without a path keep their existing behavior.
+- Keep shared App clients independent of a single-installation Layer's repository and permission scope.
+
+### Breaking
+
+- `downloadArtifactArchive` now returns an array of `{ path, bytes }` files instead of raw ZIP bytes. Install the optional `@zip.js/zip.js` peer and consume these validated files instead of passing the result to an application ZIP reader. Extraction refuses unsafe paths, symlinks, duplicate paths and file/directory conflicts, with distinct typed errors. The default caps are 100 MiB of extracted contents and a per-entry compression ratio of 100:1; set `totalSizeLimit` and `compressionRatioLimit` to change them. The existing `byteLimit` still caps the downloaded ZIP.
+- The low-level `artifacts` constructor now takes `(apiUrl, rates)` and returns an Effect. Yield it with `HttpClient`, `GitHubToken` and `TokenRefresh` provided instead of passing those services as arguments.
+
+## 0.9.0 - 2026-11-02
+
+### Added
+
+- Send PUT and DELETE through the shared authenticated mutation path, omit absent request bodies, and decode bodyless 204 results as `void` by omitting the response schema or using `Schema.Void`.
+- Find the latest commit check run by name, app ID, or both with `findLatestCheckRun`, and create or update it with `upsertCheckRun`. Check-run responses expose the app ID when present and recognize GitHub Actions-only read statuses.
+- One `githubApp` Layer now provides `GitHubApp` and `withInstallation` to share clients across installations, with separate token refresh, conditional caches and rate-limit state. The cache holds at most 100 clients, evicts the least recently used client when full and replaces clients after 30 minutes idle.
+
+### Fixed
+
+- Installation lookups and token exchanges use the same rate-limit detection and retry deadlines as App and resource requests. Quota exhaustion returns typed `GitHubRateLimited`, and requests fail locally until its deadline instead of repeating authentication requests.
+- Read HEAD responses and statuses 204, 205 and 304 as empty bytes or text; JSON decoding still rejects empty input.
+- Limit encoded responses by bytes exposed by the native client stream, without comparing compressed Content-Length to decoded bytes. Fetch exposes decompressed bytes; Node's native HTTP transport exposes encoded bytes.
+- Keep conditional response caches separate for requests with different query parameters. Refresh pagination Link metadata on 304 responses while reusing cached bodies and decoded values, so lists follow the current next page and stop when its Link disappears.
+- Remove userinfo, query strings and fragments from status-error URLs.
+- Keep pagination links on the request's origin.
+- Release response bodies before returning status or body-size failures, and keep schema failures from holding HTTP connections.
+- Release GitHub response bodies on rejection and before refreshing a rejected installation token, so repeated failures do not exhaust the connection pool.
+
+### Breaking
+
+- Effectful `GitHubToken` providers can now fail with `GitHubRateLimited` alongside `GitHubAppError`. Consumers handling authentication failures must also handle `GitHubRateLimited` and use its `retryAt` when scheduling another attempt.
+- Bounded response readers reject NaN, infinite and negative limits with the typed `InvalidBodyLimit` error from `errors.ts`. Pass a finite nonnegative byte limit and handle the new failure in the error channel.
+- GitHub methods using the bounded response reader also expose `InvalidBodyLimit` from `@shivaedev/http/errors.ts` for invalid byte limits. Supply finite nonnegative limits and handle that failure alongside existing response failures.
+- `CreateCheckRun` requires a conclusion when `status` is `completed`, with validation before any request. Consumers creating completed runs must supply `conclusion`; use `queued` or `in_progress` when no conclusion is available.
+- `CheckRunStatus` includes `waiting`, `requested` and `pending` from GitHub Actions responses. Consumers with exhaustive status handling must add these cases. GitHub App create and update inputs remain restricted to `queued`, `in_progress` and `completed`.
+- Pagination rejects automatic fetch redirects so custom headers cannot reach another origin. Pass a direct same-origin page URL instead of a redirecting URL; links to later pages must also use direct URLs. Other fetch options in the current Effect context are preserved. Use a client without redirect-following middleware.
+- GitHub listing methods inherit the redirect restriction. List the repository's current API path instead of an endpoint that redirects after a rename or transfer.
+
 ## 0.8.6 - 2026-11-01
 
 ### Fixed

package/README.md

@@ -42,7 +42,7 @@ await Effect.runPromise(program.pipe(Effect.provide(github)));
 
 The default base URL is `https://api.github.com`. Provide `GitHubConfig` from `@shivaedev/github/GitHubConfig.ts` with `{ apiUrl }` for another GitHub API endpoint.
 
-`read(path, schema)` decodes a JSON response. `list(path, itemSchema)` returns a Stream of decoded items across GitHub's Link pages, and stops fetching when consumption stops. `write(method, path, body, schema)` sends JSON with `POST` or `PATCH` and decodes its response. JSON response bodies default to a 1 MiB cap. Set `GitHubConfig.responseByteLimit` once for a client or pass a trailing byte-limit argument to these helpers for one request. The cap applies to each list page and is enforced while reading, before Schema decoding; exceeding it fails with typed `ResponseBodyTooLarge` without buffering the complete body. The conditional cache holds up to 1000 representations and keeps decoded values separate for each Schema.
+`read(path, schema)` decodes a JSON response. `list(path, itemSchema)` returns a Stream of decoded items across GitHub's Link pages, and stops fetching when consumption stops. `write(method, path, body, schema)` sends JSON with `POST`, `PATCH`, `PUT` or `DELETE` and decodes its response. Pass `undefined` for a bodyless request. For a 204 response, omit the schema to receive `void`, or pass `Schema.Void` explicitly; the service representation also supports `decode(Schema.Void)`. These mutations share authentication, quota observations and the single installation-token refresh. JSON response bodies default to a 1 MiB cap. Set `GitHubConfig.responseByteLimit` once for a client or pass a trailing byte-limit argument to these helpers for one request. The cap applies to each list page and is enforced while reading, before Schema decoding; exceeding it fails with typed `ResponseBodyTooLarge` without buffering the complete body. The conditional cache holds up to 1000 representations and keeps decoded values separate for each Schema.
 
 For large comparisons and listings, allow up to 16 MiB through the same bounded, Schema-decoded path instead of maintaining a separate fetch, body reader and decoder in the application.
 
@@ -76,7 +76,7 @@ const diff = Effect.gen(function* () {
 
 The service's `read(path)` and `write(method, path, body)` return a representation with a generic `decode(schema)` method. Its `list(path)` returns an Effect containing a Stream of page representations. These methods accept the same trailing byte limit: `read(path, byteLimit)`, `write(method, path, body, byteLimit)` and `list(path, beforeRequest, byteLimit)`; pass `undefined` for `beforeRequest` when no pacing callback is needed. Prefer the exported functions for Schema-decoded items. Each page representation exposes `hasNext`, which reports whether its Link header names a next page without fetching it. A caller with a pacing policy can pass `github.list(path, beforeRequest)`: the callback receives the resource name before each page request, and its typed failure stops the stream. `github.resource(path)` returns the observed resource for that path, defaulting to core or search before the first response.
 
-Use `listBounded(path, itemSchema, pageCap, byteLimit?)` to collect a prefix within a positive page cap. It returns `{ items, truncated }`; `truncated` is true exactly when the last fetched page names a next page. It never requests or decodes a page beyond the cap, and uses the same pagination and per-page byte limits as `list`.
+Use `listBounded(path, itemSchema, pageCap, options?)` to collect a prefix within a positive page cap. It returns `{ items, skipped, truncated }`; `truncated` is true exactly when the last fetched page names a next page. It never requests or decodes a page beyond the cap, and uses the same pagination and per-page byte limits as `list`.
 
 ```ts
 import { listBounded } from "@shivaedev/github/GitHub.ts";
@@ -84,6 +84,55 @@ import { listBounded } from "@shivaedev/github/GitHub.ts";
 const issues = listBounded("/repos/acme/widgets/issues", Issue, 2);
 ```
 
+### Enveloped lists and partial decoding
+
+`list`, `listPages` and `listBounded` accept either the existing numeric byte cap or a `ListOptions` object (from `@shivaedev/github/pagedLists.ts`) as their last argument. Set `arrayKey` to read an array inside an envelope, such as `check_runs` or `artifacts`. The options also accept `responseByteLimit` and the service's `beforeRequest` pacing callback. Item Schemas retain their decoding service requirements.
+
+```ts
+const checks = listBounded("/repos/acme/widgets/commits/main/check-runs", CheckRun, 2, {
+	arrayKey: "check_runs",
+	onDecodeError: "skip",
+	responseByteLimit: 2 * 1024 * 1024,
+});
+```
+
+Import `CheckRun` from `@shivaedev/github/checkRuns.ts`. Decoding fails at the first invalid item by default. With `onDecodeError: "skip"`, valid items keep their order and `skipped` counts rejected items across the fetched pages. Invalid JSON, a missing envelope key, a non-array value, HTTP failures and byte-limit failures still fail the read. A page containing only rejected items still follows its next Link. The page cap counts fetched pages, including empty pages, and never counts pages beyond the cap.
+
+`listPages(path, itemSchema, options?)` returns a Stream of `{ items, skipped, hasNext }` pages for consumers that need streaming counts. `list` flattens those pages into items. Both fetch only while consumed.
+
+### Daily repository reads
+
+The `GitHub` service includes Schema-decoded reads for common repository work:
+
+| Method                                                         | Result                                                             |
+| -------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `getIssue(owner, repo, number, byteLimit?)`                    | `Issue`                                                            |
+| `getUser(username, byteLimit?)`                                | `User`                                                             |
+| `getCollaboratorPermission(owner, repo, username, byteLimit?)` | `CollaboratorPermission`                                           |
+| `getCommit(owner, repo, ref, byteLimit?)`                      | `CommitDetail`, including stats and optional files                 |
+| `compareCommits(owner, repo, base, head, byteLimit?)`          | `Comparison`, including commits, optional files and `totalCommits` |
+| `getTree(owner, repo, ref, options?)`                          | `GitTree`, including GitHub's `truncated` flag                     |
+| `listIssues(owner, repo, options?)`                            | Effect containing a Stream of decoded issue pages                  |
+| `listPullRequestFiles(owner, repo, number, options?)`          | Effect containing a Stream of decoded file pages                   |
+| `listCommits(owner, repo, options?)`                           | Effect containing a Stream of decoded commit pages                 |
+
+The Schemas live in `@shivaedev/github/repositorySchemas.ts` and `@shivaedev/github/gitSchemas.ts`. Results use camelCase field names. Commit authors can be null, file patches can be absent for binary files, and renamed files expose `previousFilename`.
+
+```ts
+const review = Effect.gen(function* () {
+	const github = yield* GitHub;
+	const issue = yield* github.getIssue("acme", "widgets", 3);
+	const pages = yield* github.listPullRequestFiles("acme", "widgets", 3, { responseByteLimit: 2 * 1024 * 1024 });
+	const files = yield* pages.pipe(
+		Stream.flatMap((page) => Stream.fromIterable(page.items)),
+		Stream.runCollect,
+	);
+	return { issue, files };
+});
+```
+
+These reads share the client's authentication, conditional representations and body caps. List options accept `query` for GitHub filters such as issue `state` or commit `sha`, along with the decoding and pacing options above. Lists request `per_page=100` unless overridden in `query`. Tree options accept `recursive` and `responseByteLimit`. Refs containing slashes are encoded as path segments. Compare and single-commit reads return one GitHub response; use `totalCommits` and GitHub's endpoint limits when choosing whether the response is sufficient for your application.
+
 ### Acting as a GitHub App
 
 Provide `githubApp` as the `GitHubToken` Layer. With just the App ID and a PEM private key wrapped in `Redacted`, the client signs App JWTs for App-level requests. Add an installation ID for installation requests. Both use the same Schema-aware `read` and paginated `list` functions.
@@ -116,6 +165,43 @@ const repository = read("/repos/acme/widgets", Schema.Struct({ id: Schema.Number
 
 Provide `clients(privateKey).app` to `appInfo` or `installations`, and `.accessCheck` to `repository`, using `Effect.provide`. The `.background` client receives a full installation token. These Layers replace application-written JWT signing, installation-token exchanges, expiry timers and the resource-401 refresh wrapper; provide the client Layer once around the application or job for each installation and scope to share its token cache.
 
+A single `githubApp(credentials)` Layer also provides `GitHubApp`, whose `installation(id)` method returns a cached `GitHub` client. Use `withInstallation` to run the usual GitHub operations for a selected installation without maintaining client Layers in the application:
+
+```ts
+import { Effect, Layer, Redacted, Schema } from "effect";
+import { FetchHttpClient } from "effect/http";
+import { read } from "@shivaedev/github/GitHub.ts";
+import { githubApp } from "@shivaedev/github/githubApp.ts";
+import { withInstallation } from "@shivaedev/github/installationClients.ts";
+
+const app = (privateKey: Redacted.Redacted<string>) => githubApp({ appId: "123456", privateKey }).pipe(Layer.provide(FetchHttpClient.layer));
+const Repositories = Schema.Struct({ repositories: Schema.Array(Schema.Struct({ id: Schema.Number, name: Schema.String })) });
+const repositories = read("/installation/repositories", Repositories);
+const bothInstallations = Effect.all([withInstallation(7, repositories), withInstallation(8, repositories)]);
+```
+
+Provide `app(privateKey)` once around `bothInstallations` or the application. Each installation has its own full-access token, conditional representations and rate-limit state. A 401 refreshes only that installation's rejected token; a rate limit blocks only that installation's resource. Existing scoped single-installation Layers remain available for access checks.
+
+The shared cache holds at most 100 installation clients and evicts the least recently used client when full. Selecting a client renews its 30-minute idle lifetime; a client idle for that interval is replaced on its next selection. Expiry is lazy, with no background timer. Eviction discards the client's token and request state, and its next request exchanges a new token. Keep operations inside `withInstallation` so each selection uses the cache's current client.
+
+### Repositories visible to an account
+
+Pass the GitHub account from your application's session to `GitHubApp.viewerRepositories(account)`. A number is a GitHub account ID; a string is a login. Provide the same `githubApp(credentials)` Layer as above. The package has no dependency on your session or identity service.
+
+```ts
+import { Effect } from "effect";
+import { GitHubApp } from "@shivaedev/github/installationClients.ts";
+
+const access = Effect.gen(function* () {
+	const app = yield* GitHubApp;
+	return yield* app.viewerRepositories(12345);
+});
+```
+
+The result contains `readable` and `administrable` arrays. Each entry has `id`, `name`, `owner.login`, `htmlUrl`, `private` and `installationId`. Only repositories installed for this App are included, across all installation and repository pages. Public repositories are readable even without a collaborator grant. Private repositories require GitHub's `read`, `triage`, `write`, `maintain` or `admin` permission; only `admin` grants administration. A permission lookup returning 404 means no collaborator grant. Other lookup failures fail the operation instead of returning partial access. The App needs repository Metadata read permission for these lookups.
+
+Successful results are cached for 60 seconds, across at most 100 account keys, evicting the least recently used key when full. Login casing shares a key. Reads do not extend the lifetime. After expiry, the next call revalidates installation lists, repository lists and permissions, so revoked access, changed roles and removed repositories remain cached for at most that interval. Failed lookups are immediately eligible for another attempt. These are cached observations of GitHub access; the application chooses its authorization policy.
+
 `scope` accepts `repositoryIds` or `repositories` (repository names), and a `permissions` record of GitHub permission names to `"read"`, `"write"` or `"admin"`. Omit `scope` for the installation's full access. Explicit `{ permissions: { metadata: "read" } }` requests a metadata-only token for access checks. GitHub decides whether the requested scope is allowed.
 
 Alternatively, pass `{ appId, privateKey, owner: "acme", repository: "widgets", scope? }`. The Layer resolves the installation through `GET /repos/{owner}/{repo}/installation` before exchanging the App JWT for an installation token. Signing uses Node's built-in crypto. The RS256 JWT carries the App ID as `iss`, `iat` 60 seconds before the current time, and `exp` ten minutes ahead.
@@ -124,28 +210,53 @@ Alternatively, pass `{ appId, privateKey, owner: "acme", repository: "widgets",
 
 An installation token is fetched on the first request and reused until five minutes before `expires_at`, using Effect's Clock. Concurrent requests through the same Layer share the in-flight exchange, including at refresh. A resource 401 invalidates only the rejected cached token and retries once with a newly exchanged token; simultaneous 401s share that exchange. A second 401 fails with typed `RemoteUnauthorized`. App-level JWTs and custom tokens are not automatically retried.
 
-App authentication failures use `GitHubAppError` from `errors.ts`. Its string `reason` distinguishes `"sign"` (JWT signing), `"encode"` (request body encoding), `"transport"` (sending or reading the response), `"status"` (an HTTP refusal) and `"response"` (invalid or oversized response data). A refused exchange or installation lookup with HTTP 401 has `{ reason: "status", status: 401 }`. Caught failures remain available as a non-enumerable `cause`, excluded from JSON serialization; causes can contain credentials from the underlying HTTP request, so keep them in trusted diagnostics. The serialized errors, logs and spans exclude the private key, App JWT and installation token.
+Installation lookups and token exchanges follow the same primary and secondary rate-limit rules as resource and App-level requests: they fail with `GitHubRateLimited` and block further authentication requests locally until `retryAt`. Retry scheduling belongs to the caller.
+
+Other App authentication failures use `GitHubAppError` from `errors.ts`. Its string `reason` distinguishes `"sign"` (JWT signing), `"encode"` (request body encoding), `"transport"` (sending or reading the response), `"status"` (an HTTP refusal) and `"response"` (invalid or oversized response data). A refused exchange or installation lookup with HTTP 401 has `{ reason: "status", status: 401 }`. Caught failures remain available as a non-enumerable `cause`, excluded from JSON serialization; causes can contain credentials from the underlying HTTP request, so keep them in trusted diagnostics. The serialized errors, logs and spans exclude the private key, App JWT and installation token.
 
-### Downloading workflow-artifact archives
+### Downloading and extracting workflow artifacts
 
-Call `downloadArtifactArchive` with the artifact ID and a byte cap. It requests GitHub's ZIP endpoint with the current installation token, reads the 302 Location explicitly, and issues a fresh request to storage without the GitHub Authorization or API-version headers. Fetch requests use manual redirects and omit ambient credentials; provide an HTTP client without automatic redirect middleware.
+Install the optional ZIP reader to extract artifacts:
+
+```sh
+pnpm add @zip.js/zip.js
+```
+
+Call `downloadArtifactArchive` with the artifact ID and a download byte cap. It requests GitHub's ZIP endpoint with the current installation token, reads the 302 Location explicitly, and issues a fresh request to storage without the GitHub Authorization or API-version headers. Fetch requests use manual redirects and omit ambient credentials; provide an HTTP client without automatic redirect middleware.
 
 ```ts
 import { Effect } from "effect";
 import { GitHub } from "@shivaedev/github/GitHub.ts";
 
-const archive = Effect.gen(function* () {
+const files = Effect.gen(function* () {
 	const github = yield* GitHub;
 	return yield* github.downloadArtifactArchive({
 		owner: "acme",
 		repo: "widgets",
 		artifactId: 7,
 		byteLimit: 10 * 1024 * 1024,
+		totalSizeLimit: 100 * 1024 * 1024,
+		compressionRatioLimit: 100,
 	});
 });
 ```
 
-Provide an installation client such as `clients(privateKey).background` from the GitHub App example above. The result is a `Uint8Array` of archive bytes. The package counts bytes while streaming, independently of transport limits, and stops on overflow with `GitHubArtifactTooLarge({ limit })` from `errors.ts`. This replaces application-owned redirect handling and archive body limits. It does not extract the ZIP.
+Provide an installation client such as `clients(privateKey).background` from the GitHub App example above. The result is an array of `{ path, bytes }` files (`ArtifactFile` from `artifactExtraction.ts`), with relative POSIX paths and `Uint8Array` contents. Directory entries are validated and omitted from the result. Extraction happens in memory and writes no files. The ZIP reader loads on demand; other GitHub operations do not need it.
+
+`byteLimit` caps the downloaded ZIP while streaming and fails with `GitHubArtifactTooLarge({ limit })` from `errors.ts`. Extraction defaults to a `totalSizeLimit` of 100 MiB across all entries and a per-entry `compressionRatioLimit` of 100:1. Both caps are inclusive. The total limit must be a non-negative safe integer; the ratio must be finite and positive. Limits check declared sizes before decompression and emitted bytes before retaining them. No partial file list is returned after a refusal.
+
+Extraction failures come from `artifactErrors.ts`:
+
+| Error                                             | Refusal                                                                                                           |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `GitHubArtifactPathTraversal({ path })`           | Absolute paths, drive paths, backslashes, colons, NUL, empty or dot path components, and parent traversal         |
+| `GitHubArtifactSymlink({ path })`                 | Symbolic links                                                                                                    |
+| `GitHubArtifactDuplicateEntry({ path })`          | Duplicate paths and file/directory conflicts                                                                      |
+| `GitHubArtifactCompressionRatio({ path, limit })` | An entry exceeds the ratio cap                                                                                    |
+| `GitHubArtifactExtractedTooLarge({ limit })`      | Combined extracted contents exceed the total cap                                                                  |
+| `GitHubArtifactExtractionError({ reason })`       | Missing reader (`"reader-unavailable"`), malformed ZIP (`"invalid-archive"`) or invalid caps (`"invalid-limits"`) |
+
+Paths remain case-sensitive.
 
 A missing (404) or expired (410) artifact fails with `GitHubArtifactError({ stage: "redirect", status })`. A storage HTTP failure uses the same error with `stage: "download"`. Transport and GitHub rate-limit failures retain their usual typed errors.
 
@@ -189,7 +300,30 @@ const report = Effect.gen(function* () {
 });
 ```
 
-`createCheckRun(owner, repo, input)` creates a check for `headSha` with a name and status. `updateCheckRun(owner, repo, id, input)` moves it to `in_progress` or `completed`; completion requires a conclusion. Output contains `title`, `summary` and optional `text`. An optional `detailsUrl` on creation and either update shape links to an external report; the returned `CheckRun.detailsUrl` is the GitHub URL or `null` when none exists. It is sent and decoded as `details_url`. Request and response Schemas are exported from `checkRuns.ts`.
+`createCheckRun(owner, repo, input)` creates a check for `headSha` with a name and status. `updateCheckRun(owner, repo, id, input)` moves it to `in_progress` or `completed`; both creation and update with `status: "completed"` require a conclusion, including runtime validation before any request. Output contains `title`, `summary` and optional `text`. An optional `detailsUrl` on creation and either update shape links to an external report; the returned `CheckRun.detailsUrl` is the GitHub URL or `null` when none exists. It is sent and decoded as `details_url`. Request and response Schemas are exported from `checkRuns.ts`.
+
+`findLatestCheckRun(owner, repo, { headSha, name?, appId? })` pages the commit's check runs and returns an `Option<CheckRun>`. Supply a name, an app ID, or both; both filters must match when supplied together. It selects the greatest run ID across all pages. `CheckRun.app` exposes the app ID when GitHub supplies it. Read statuses include GitHub Actions-only `waiting`, `requested` and `pending`, so another app's run in one of those states does not prevent ownership lookup.
+
+`upsertCheckRun(owner, repo, input, appId?)` uses the same name and commit lookup, then updates the latest match or creates a run when none exists. Pass the app ID to keep another app's same-named check untouched. Without an app ID, use a name unique to your app. A lookup failure propagates without creating a run. Lookup and mutation are separate GitHub requests, so concurrent callers can create duplicates; callers own serialization.
+
+```ts
+const publishCheck = (headSha: string) =>
+	Effect.gen(function* () {
+		const github = yield* GitHub;
+		return yield* github.upsertCheckRun(
+			"acme",
+			"widgets",
+			{
+				headSha,
+				name: "Coverage",
+				status: "completed",
+				conclusion: "success",
+				output: { title: "Coverage", summary: "90% covered" },
+			},
+			123456,
+		);
+	});
+```
 
 ```ts
 const check = (headSha: string) =>