@effected/github 0.24.0 → 0.25.0

package/Attestation.js

@@ -12,6 +12,10 @@ import { Context, Effect, Layer, Schema } from "effect";
 * with a stated sunset. Pinning the version means the response is on a contract
 * the generated types do not describe — which is why this module is the one that
 * uses `requestDecoded` with owned schemas rather than the route table.
+*
+* Sent as a per-call header, which wins over the client's own
+* `apiVersion`, so these reads stay on this contract even when a consumer
+* pins the client to another version.
 */
 const API_VERSION = "2026-03-10";
 /**

package/GitHubApp.js

@@ -1,7 +1,7 @@
 import { GitHubError } from "./GitHubError.js";
 import { GitHubGraphQLError } from "./GraphQL.js";
 import { unstubbed } from "./internal/unstubbed.js";
-import { GitHubClient, makeClientShape } from "./GitHubClient.js";
+import { GitHubClient, makeClientShape, resolveApiVersion } from "./GitHubClient.js";
 import { numericId } from "./internal/ids.js";
 import { InstallationTokenStore } from "./InstallationTokenStore.js";
 import { Cause, Clock, Context, DateTime, Deferred, Duration, Effect, Layer, Option, Redacted, Ref, Schema, Semaphore, Stream } from "effect";
@@ -544,7 +544,7 @@ const asBearer = (token, options) => makeClientShape({
 });
 const appFailure = (kind) => (error) => Effect.fail(GitHubAppError.of(kind, error.reason, error));
 function makeApp(options) {
-	return Effect.sync(() => {
+	return Effect.map(resolveApiVersion(options.apiVersion), () => {
 		const installations = Effect.fn("GitHubApp.installations")(function* (credentials) {
 			return (yield* (yield* asApp(credentials, options)).paginate("GET /app/installations", {}).pipe(Effect.catch(appFailure("installation")))).map((entry) => {
 				const account = entry.account ?? void 0;
@@ -634,6 +634,7 @@ const normalizePermissions = (raw) => {
 * release.
 */
 const makeRotatingClient = (mint, release, options, operation) => Effect.gen(function* () {
+	const apiVersion = yield* resolveApiVersion(options.apiVersion);
 	const held = yield* Ref.make(Option.none());
 	const revokeHeld = Effect.flatMap(Ref.get(held), (current) => Option.isSome(current) ? Effect.ignore(release(current.value.credential.token)) : Effect.void);
 	const rotate = Effect.gen(function* () {
@@ -678,7 +679,8 @@ const makeRotatingClient = (mint, release, options, operation) => Effect.gen(fun
 		paginate: (route, params, pageOptions) => Effect.flatMap(current, (client) => client.paginate(route, params, pageOptions)),
 		paginateStream: (route, params, pageOptions) => Stream.unwrap(Effect.map(current, (client) => client.paginateStream(route, params, pageOptions))),
 		graphql: (document, variables) => Effect.flatMap(currentForGraphQL, (client) => client.graphql(document, variables)),
-		rateLimit: Effect.flatMap(Ref.get(held), (state) => Option.isSome(state) ? state.value.client.rateLimit : Effect.succeed(Option.none()))
+		rateLimit: Effect.flatMap(Ref.get(held), (state) => Option.isSome(state) ? state.value.client.rateLimit : Effect.succeed(Option.none())),
+		apiVersion
 	};
 });
 

package/GitHubClient.js

@@ -1,7 +1,7 @@
 import { GitHubError } from "./GitHubError.js";
 import { GitHubGraphQLError } from "./GraphQL.js";
 import { RetryPolicy } from "./Resilience.js";
-import { makeTransport } from "./internal/octokit.js";
+import { DEFAULT_API_VERSION, makeTransport } from "./internal/octokit.js";
 import { fromArray, paginate } from "./internal/paginate.js";
 import { unstubbed } from "./internal/unstubbed.js";
 import { Clock, Config, Context, Effect, Layer, Option, Schema, Stream } from "effect";
@@ -149,11 +149,14 @@ var GitHubClient = class GitHubClient extends Context.Service()("@effected/githu
 	* member **dies** naming itself.
 	*
 	* @remarks
-	* No member has an honest default. A fabricated response — an empty list, a
+	* No request member has an honest default. A fabricated response — an empty list, a
 	* made-up sha — would leak into the code under test as fact, so the double
 	* fails loudly instead, which also makes it proof that a test touches nothing
 	* but what it stubbed.
 	*
+	* `rateLimit` answers `Option.none()` and `apiVersion` the live default,
+	* because a real client legitimately answers both without a request.
+	*
 	* For recorded responses that page for real, use
 	* {@link GitHubClient.layerFixture}.
 	*/
@@ -163,7 +166,8 @@ var GitHubClient = class GitHubClient extends Context.Service()("@effected/githu
 		paginate: overrides.paginate ?? (() => dies("paginate")),
 		paginateStream: overrides.paginateStream ?? (() => Stream.fromEffect(dies("paginateStream"))),
 		graphql: overrides.graphql ?? (() => dies("graphql")),
-		rateLimit: overrides.rateLimit ?? Effect.succeed(Option.none())
+		rateLimit: overrides.rateLimit ?? Effect.succeed(Option.none()),
+		apiVersion: overrides.apiVersion ?? "2026-03-10"
 	});
 	/** {@link GitHubClient.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(GitHubClient, GitHubClient.makeTest(overrides));
@@ -188,6 +192,21 @@ var GitHubClient = class GitHubClient extends Context.Service()("@effected/githu
 	*/
 	static layerFixture = (fixtures) => Layer.succeed(GitHubClient, makeFixture(fixtures));
 };
+/** A calendar api-version: `YYYY-MM-DD`. */
+const API_VERSION_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+/**
+* The api-version a client pins: the option when it is a calendar version,
+* the default when it is absent, and a defect naming the option otherwise.
+*
+* @remarks
+* A defect, not a typed failure: a malformed version is a wiring mistake no
+* caller recovers from, and every layer that builds a client would otherwise
+* widen its error channel for it. Exported for `GitHubApp`, which validates
+* eagerly at its own layer construction. Not part of the public surface.
+*
+* @internal
+*/
+const resolveApiVersion = (option) => option === void 0 ? Effect.succeed(DEFAULT_API_VERSION) : API_VERSION_PATTERN.test(option) ? Effect.succeed(option) : Effect.die(/* @__PURE__ */ new Error(`GitHubClient: the apiVersion option must be a calendar version like "${DEFAULT_API_VERSION}" (YYYY-MM-DD), got ${JSON.stringify(option)}`));
 /**
 * Builds the live shape over a constructed transport.
 *
@@ -199,12 +218,14 @@ var GitHubClient = class GitHubClient extends Context.Service()("@effected/githu
 * @internal
 */
 const makeClientShape = (options) => Effect.gen(function* () {
+	const apiVersion = yield* resolveApiVersion(options.apiVersion);
 	const transport = yield* makeTransport({
 		token: options.token,
 		retry: resolvePolicy(options.retry),
 		baseUrl: options.baseUrl,
 		userAgent: options.userAgent,
-		fetch: options.fetch
+		fetch: options.fetch,
+		apiVersion
 	});
 	const request = Effect.fn("GitHubClient.request")(function* (route, params) {
 		yield* Effect.annotateCurrentSpan({ route });
@@ -236,7 +257,8 @@ const makeClientShape = (options) => Effect.gen(function* () {
 			const raw = yield* transport.graphql(document.name, document.document, document.encodeVariables(variables));
 			return yield* document.decode(raw).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubGraphQLError.decode(document.name, "response did not match its schema", error))));
 		}),
-		rateLimit: transport.rateLimit
+		rateLimit: transport.rateLimit,
+		apiVersion
 	};
 });
 const makeFixture = (fixtures) => {
@@ -303,8 +325,9 @@ const makeFixture = (fixtures) => {
 			const raw = fixtures.graphql?.[document.name];
 			return raw === void 0 ? Effect.die(/* @__PURE__ */ new Error(`GitHubClient.layerFixture: no graphql fixture for ${document.name}`)) : document.decode(raw).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubGraphQLError.decode(document.name, "fixture did not match its schema", error))));
 		},
-		rateLimit: Effect.succeed(Option.fromUndefinedOr(fixtures.rateLimit))
+		rateLimit: Effect.succeed(Option.fromUndefinedOr(fixtures.rateLimit)),
+		apiVersion: fixtures.apiVersion ?? "2026-03-10"
 	};
 };
 
-export { GitHubClient, GitHubFixtures, RawFailure, makeClientShape };
+export { GitHubClient, GitHubFixtures, RawFailure, makeClientShape, resolveApiVersion };

package/GitHubIssue.js

@@ -142,29 +142,6 @@ var GitHubIssue = class GitHubIssue extends Context.Service()("@effected/github/
 	static layerTest = (overrides = {}) => Layer.succeed(GitHubIssue, GitHubIssue.makeTest(overrides));
 };
 const dies = unstubbed("GitHubIssue.makeTest");
-/**
-* The REST calendar version this module's requests pin.
-*
-* @remarks
-* The routes are not deprecated — the **default api-version** is. When no
-* `x-github-api-version` header is sent (octokit sends none), GitHub serves
-* calendar version 2022-11-28, which it deprecated when 2026-03-10 shipped and
-* sunsets on 2028-03-10. Every response from an endpoint the new version
-* changed then carries a `Deprecation` header, which `@octokit/request` prints
-* straight to the consumer's console — the constructor's `log` option cannot
-* silence it, because the fetch wrapper resolves `request.log ?? console`.
-* `PATCH /repos/{owner}/{repo}/issues/{issue_number}` is on that list (the
-* singular `assignee` parameter was removed), so every `close` warned once per
-* issue in consumer workflow logs.
-*
-* Nothing this module sends or reads changed in 2026-03-10: `state` and
-* `state_reason` are untouched, and the projections read only fields both
-* versions carry. Pinning the current version is therefore the whole fix, and
-* it deliberately does **not** hide future deprecations — when GitHub
-* deprecates 2026-03-10 in turn, the header comes back and octokit warns
-* again.
-*/
-const API_VERSION_HEADERS = { "x-github-api-version": "2026-03-10" };
 /** GitHub sends a label as either a string or an object; callers want the name. */
 const labelNames = (labels) => labels.flatMap((label) => typeof label === "string" ? [label] : label.name !== void 0 ? [label.name] : []);
 const project = (raw) => IssueInfo.make({
@@ -186,8 +163,7 @@ const make = (client) => ({
 		const raw = yield* client.request("GET /repos/{owner}/{repo}/issues/{issue_number}", {
 			owner,
 			repo,
-			issue_number: number,
-			headers: API_VERSION_HEADERS
+			issue_number: number
 		});
 		return project(raw);
 	}),
@@ -201,8 +177,7 @@ const make = (client) => ({
 			owner,
 			repo,
 			...options?.state !== void 0 ? { state: options.state } : {},
-			...options?.labels !== void 0 ? { labels: options.labels.join(",") } : {},
-			headers: API_VERSION_HEADERS
+			...options?.labels !== void 0 ? { labels: options.labels.join(",") } : {}
 		}, options?.page)).map(project);
 	}),
 	close: Effect.fn("GitHubIssue.close")(function* (number, reason) {
@@ -217,8 +192,7 @@ const make = (client) => ({
 			repo,
 			issue_number: number,
 			state: "closed",
-			...reason !== void 0 ? { state_reason: reason } : {},
-			headers: API_VERSION_HEADERS
+			...reason !== void 0 ? { state_reason: reason } : {}
 		});
 	}),
 	comment: Effect.fn("GitHubIssue.comment")(function* (number, body) {
@@ -232,8 +206,7 @@ const make = (client) => ({
 			owner,
 			repo,
 			issue_number: number,
-			body,
-			headers: API_VERSION_HEADERS
+			body
 		});
 		return numericId(created.id);
 	}),
@@ -248,8 +221,7 @@ const make = (client) => ({
 		const existing = (yield* client.paginate("GET /repos/{owner}/{repo}/issues/{issue_number}/comments", {
 			owner,
 			repo,
-			issue_number: issueNumber,
-			headers: API_VERSION_HEADERS
+			issue_number: issueNumber
 		})).find((comment) => marker.matches(comment.body ?? ""));
 		if (existing !== void 0) return CommentOnceResult.make({
 			wrote: false,
@@ -263,8 +235,7 @@ const make = (client) => ({
 			owner,
 			repo,
 			issue_number: issueNumber,
-			body: `${body}\n\n${marker.html}`,
-			headers: API_VERSION_HEADERS
+			body: `${body}\n\n${marker.html}`
 		});
 		return CommentOnceResult.make({
 			wrote: true,

package/GitHubRepository.js

@@ -2,6 +2,7 @@ import { GraphQLDocument } from "./GraphQL.js";
 import { unstubbed, unstubbedRead } from "./internal/unstubbed.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
+import { REMOVED_BY_PINNED_VERSION, REPOSITORY_REST_SETTING_KEYS } from "./internal/repositoryRestSettingKeys.js";
 import { Context, Effect, Layer, Schema } from "effect";
 
 // src/GitHubRepository.ts
@@ -64,17 +65,21 @@ const SECURITY_ANALYSIS_STATUS_FIELDS = /* @__PURE__ */ new Set([
 	"dependabot_security_updates"
 ]);
 /**
-* Settings reachable **only** through the GraphQL `updateRepository` mutation,
-* mapped from snake_case keys to camelCase GraphQL input fields.
+* Settings written through the GraphQL `updateRepository` mutation, mapped
+* from snake_case keys to camelCase GraphQL input fields.
 *
 * @remarks
-* GitHub never exposed these on the REST repository endpoint — the
-* `PATCH /repos/{owner}/{repo}` route accepts none of them, and
-* `has_discussions` is the treacherous one: the REST **read** returns it, so
-* routing its write to the PATCH looks symmetric, but the PATCH silently
-* ignores unknown body fields and answers 200, so the write would look applied
-* while the repository never changed. Setting any of these forces a second
-* round trip to learn the repository's node id.
+* `applySettings` checks this map **first**, so a key here always goes
+* through GraphQL, even when the REST patch also declares it.
+* `has_sponsorships` and `has_discussions` are GraphQL-only: the
+* `PATCH /repos/{owner}/{repo}` route accepts neither, and `has_discussions`
+* is the treacherous one — the REST **read** returns it, so routing its write
+* to the PATCH looks symmetric, but the PATCH silently ignores unknown body
+* fields and answers 200, so the write would look applied while the
+* repository never changed. `has_pull_requests` is in the REST patch's body
+* too; GraphQL is preferred for it so the three toggles travel together.
+* Setting any of these forces a second round trip to learn the repository's
+* node id.
 *
 * @public
 */
@@ -171,12 +176,13 @@ const preparePatch = (patch) => {
 };
 /**
 * Read and update a repository's settings, including settings only GraphQL can
-* write, and look up its default branch, node id and owner type.
+* write, read and replace its topics, and look up its default branch, node id
+* and owner type.
 *
 * @remarks
 * Provide it with {@link GitHubRepository.layer}, which needs a `GitHubClient`;
-* every member also needs a `Repo` in `R`. `settings`, `defaultBranch`, `nodeId`
-* and `ownerType` are `Effect` values, not functions.
+* every member also needs a `Repo` in `R`. `settings`, `defaultBranch`, `nodeId`,
+* `ownerType` and `topics` are `Effect` values, not functions.
 *
 * @example
 * ```ts
@@ -187,7 +193,7 @@ const preparePatch = (patch) => {
 *   const repository = yield* GitHubRepository;
 *   const branch = yield* repository.defaultBranch;
 *   const applied = yield* repository.applySettings({ has_wiki: false, has_discussions: true });
-*   return { branch, applied }; // applied.rest, applied.graphql
+*   return { branch, applied }; // applied.rest, applied.graphql, applied.ignored
 * });
 * ```
 *
@@ -203,7 +209,9 @@ var GitHubRepository = class GitHubRepository extends Context.Service()("@effect
 		defaultBranch: overrides.defaultBranch ?? unread("defaultBranch"),
 		nodeId: overrides.nodeId ?? unread("nodeId"),
 		ownerType: overrides.ownerType ?? unread("ownerType"),
-		applySettings: overrides.applySettings ?? (() => dies("applySettings"))
+		applySettings: overrides.applySettings ?? (() => dies("applySettings")),
+		topics: overrides.topics ?? unread("topics"),
+		setTopics: overrides.setTopics ?? (() => dies("setTopics"))
 	});
 	/** {@link GitHubRepository.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(GitHubRepository, GitHubRepository.makeTest(overrides));
@@ -229,6 +237,30 @@ const make = (client) => {
 	})();
 	return {
 		settings,
+		topics: Effect.fn("GitHubRepository.topics")(function* () {
+			const { owner, repo } = yield* Repo;
+			yield* Effect.annotateCurrentSpan({
+				owner,
+				repo
+			});
+			return (yield* client.request("GET /repos/{owner}/{repo}/topics", {
+				owner,
+				repo
+			})).names;
+		})(),
+		setTopics: Effect.fn("GitHubRepository.setTopics")(function* (names) {
+			const { owner, repo } = yield* Repo;
+			yield* Effect.annotateCurrentSpan({
+				owner,
+				repo,
+				topics: names.length
+			});
+			return (yield* client.request("PUT /repos/{owner}/{repo}/topics", {
+				owner,
+				repo,
+				names: [...names]
+			})).names;
+		}),
 		updateSettings: Effect.fn("GitHubRepository.updateSettings")(function* (patch) {
 			const { owner, repo } = yield* Repo;
 			yield* Effect.annotateCurrentSpan({
@@ -254,6 +286,7 @@ const make = (client) => {
 			const rest = {};
 			const graphql = {};
 			const graphqlKeys = [];
+			const ignored = [];
 			for (const [key, value] of Object.entries(input)) {
 				const graphqlField = Object.hasOwn(GRAPHQL_ONLY_SETTINGS, key) ? GRAPHQL_ONLY_SETTINGS[key] : void 0;
 				if (graphqlField !== void 0) {
@@ -261,6 +294,11 @@ const make = (client) => {
 					graphqlKeys.push(key);
 					continue;
 				}
+				const removedIn = Object.hasOwn(REMOVED_BY_PINNED_VERSION, key) ? REMOVED_BY_PINNED_VERSION[key] : void 0;
+				if (!REPOSITORY_REST_SETTING_KEYS.has(key) || removedIn !== void 0 && client.apiVersion >= removedIn) {
+					ignored.push(key);
+					continue;
+				}
 				rest[key] = value;
 			}
 			const prepared = preparePatch(rest);
@@ -282,7 +320,8 @@ const make = (client) => {
 			}
 			return {
 				rest: restKeys,
-				graphql: graphqlKeys
+				graphql: graphqlKeys,
+				ignored
 			};
 		})
 	};

package/PullRequest.js

@@ -1,5 +1,5 @@
 import { GitHubError } from "./GitHubError.js";
-import { GraphQLDocument } from "./GraphQL.js";
+import { GitHubGraphQLError, GraphQLDocument } from "./GraphQL.js";
 import { unstubbed } from "./internal/unstubbed.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
@@ -55,7 +55,27 @@ var PullRequestInfo = class extends Schema.Class("PullRequestInfo")({
 	mergedAt: Schema.Option(Schema.DateTimeUtcFromString),
 	/** The description, when GitHub sent one. */
 	body: Schema.optionalKey(Schema.String),
-	/** The merge commit, once there is one. */
+	/**
+	* The sha of the commit the merge produced; absent until the pull request
+	* has merged.
+	*
+	* @remarks
+	* Read from GraphQL's `PullRequest.mergeCommit.oid`. The REST pull request
+	* object no longer carries `merge_commit_sha` under the api-version this
+	* package pins, so a merged pull request costs one extra GraphQL round trip
+	* per single read (`get`, `update`, `upsert`), and an open or
+	* closed-unmerged one costs nothing. When the REST response does carry the
+	* field (a client pinned to an older api-version), it is used for a merged
+	* pull request and the GraphQL read is skipped.
+	*
+	* **A list read leaves it absent unless asked.** `list` and
+	* `listAssociatedWithCommit` fill it only when called with
+	* `mergeCommits: true`, at one GraphQL call per 100 merged pull requests.
+	*
+	* It is never the speculative test-merge commit GitHub computes for an open
+	* pull request, so `mergeCommitSha === sha` means "this commit is what the
+	* pull request merged as".
+	*/
 	mergeCommitSha: Schema.optionalKey(Schema.String)
 }) {};
 const AutoMergeResponse = Schema.Struct({});
@@ -75,6 +95,24 @@ const DisableAutoMerge = GraphQLDocument.make({
 }`,
 	response: AutoMergeResponse
 })();
+/**
+* One answer per requested id, **in request order**: a merged pull request
+* carries its merge commit, and a node of another type answers `{}`.
+*/
+const MergeCommitsResponse = Schema.Struct({ nodes: Schema.Array(Schema.NullOr(Schema.Struct({ mergeCommit: Schema.optionalKey(Schema.NullOr(Schema.Struct({ oid: Schema.String }))) }))) });
+const MergeCommits = GraphQLDocument.make({
+	name: "PullRequestMergeCommits",
+	document: `query PullRequestMergeCommits($ids: [ID!]!) {
+  nodes(ids: $ids) {
+    ... on PullRequest { mergeCommit { oid } }
+  }
+}`,
+	response: MergeCommitsResponse
+})();
+/** GraphQL's `nodes(ids:)` accepts at most this many ids per call. */
+const NODES_PER_QUERY = 100;
+/** How many `nodes(ids:)` calls a list's merge-commit read keeps in flight. */
+const MERGE_COMMIT_CONCURRENCY = 4;
 /** GraphQL spells the merge methods in capitals. */
 const GRAPHQL_MERGE_METHOD = {
 	merge: "MERGE",
@@ -130,27 +168,63 @@ var PullRequest = class PullRequest extends Context.Service()("@effected/github/
 };
 const dies = unstubbed("PullRequest.makeTest");
 const project = (raw) => Effect.try({
-	try: () => PullRequestInfo.make({
-		number: raw.number,
-		nodeId: raw.node_id,
-		url: raw.html_url,
-		title: raw.title,
-		state: raw.state === "closed" ? "closed" : "open",
-		head: raw.head.ref,
-		headSha: raw.head.sha,
-		base: raw.base.ref,
-		baseSha: raw.base.sha,
-		draft: raw.draft ?? false,
-		merged: raw.merged ?? raw.merged_at != null,
-		mergedAt: raw.merged_at == null ? Option.none() : Option.some(DateTime.makeUnsafe(raw.merged_at)),
-		...raw.body != null ? { body: raw.body } : {},
-		...raw.merge_commit_sha != null ? { mergeCommitSha: raw.merge_commit_sha } : {}
-	}),
+	try: () => {
+		const merged = raw.merged ?? raw.merged_at != null;
+		return PullRequestInfo.make({
+			number: raw.number,
+			nodeId: raw.node_id,
+			url: raw.html_url,
+			title: raw.title,
+			state: raw.state === "closed" ? "closed" : "open",
+			head: raw.head.ref,
+			headSha: raw.head.sha,
+			base: raw.base.ref,
+			baseSha: raw.base.sha,
+			draft: raw.draft ?? false,
+			merged,
+			mergedAt: raw.merged_at == null ? Option.none() : Option.some(DateTime.makeUnsafe(raw.merged_at)),
+			...raw.body != null ? { body: raw.body } : {},
+			...raw.merge_commit_sha != null && merged ? { mergeCommitSha: raw.merge_commit_sha } : {}
+		});
+	},
 	catch: (error) => GitHubError.decode("PullRequest", "GitHub returned an unexpected pull request", error)
 });
 /** `owner:branch` is what GitHub's `head` filter wants for a cross-fork search. */
 const qualifyHead = (owner, head) => head.includes(":") ? head : `${owner}:${head}`;
 const make = (client) => {
+	/**
+	* Fill `mergeCommitSha` for every merged pull request that lacks it, from
+	* GraphQL, in as few `nodes(ids:)` calls as the batch limit allows.
+	*
+	* @remarks
+	* The REST object stopped carrying `merge_commit_sha`, and the field is an
+	* `optionalKey`, so without this it would decode clean as always-absent —
+	* a silent break for anything matching a commit against it. Nothing is
+	* requested when no pull request in the batch needs it.
+	*
+	* `nodes(ids:)` answers positionally — one entry per id, in order, `null`
+	* for an id that resolves to nothing — so each answer is joined to the id
+	* at its index. An answer of the wrong length cannot be joined that way and
+	* fails as a decode error rather than pairing shas with the wrong pulls.
+	*/
+	const withMergeCommits = (pulls) => {
+		const ids = pulls.filter((pull) => pull.merged && pull.mergeCommitSha === void 0).map((pull) => pull.nodeId);
+		if (ids.length === 0) return Effect.succeed(pulls);
+		const batches = [];
+		for (let i = 0; i < ids.length; i += NODES_PER_QUERY) batches.push(ids.slice(i, i + NODES_PER_QUERY));
+		return Effect.forEach(batches, (batch) => Effect.flatMap(client.graphql(MergeCommits, { ids: batch }), (answer) => answer.nodes.length === batch.length ? Effect.succeed(batch.map((id, index) => [id, answer.nodes[index]?.mergeCommit?.oid])) : Effect.fail(GitHubGraphQLError.decode(MergeCommits.name, `nodes(ids:) answered ${answer.nodes.length} entries for ${batch.length} ids`))), { concurrency: MERGE_COMMIT_CONCURRENCY }).pipe(Effect.map((answers) => {
+			const oids = /* @__PURE__ */ new Map();
+			for (const [id, oid] of answers.flat()) if (oid !== void 0) oids.set(id, oid);
+			return pulls.map((pull) => {
+				const oid = pull.mergeCommitSha === void 0 ? oids.get(pull.nodeId) : void 0;
+				return oid === void 0 ? pull : PullRequestInfo.make({
+					...pull,
+					mergeCommitSha: oid
+				});
+			});
+		}));
+	};
+	const withMergeCommit = (pull) => Effect.map(withMergeCommits([pull]), (pulls) => pulls[0] ?? pull);
 	const list = Effect.fn("PullRequest.list")(function* (options) {
 		const { owner, repo } = yield* Repo;
 		const raw = yield* client.paginate("GET /repos/{owner}/{repo}/pulls", {
@@ -160,7 +234,8 @@ const make = (client) => {
 			...options?.head !== void 0 ? { head: qualifyHead(owner, options.head) } : {},
 			...options?.base !== void 0 ? { base: options.base } : {}
 		}, options?.page);
-		return yield* Effect.forEach(raw, project);
+		const pulls = yield* Effect.forEach(raw, project);
+		return options?.mergeCommits === true ? yield* withMergeCommits(pulls) : pulls;
 	});
 	const create = Effect.fn("PullRequest.create")(function* (input) {
 		const { owner, repo } = yield* Repo;
@@ -197,7 +272,7 @@ const make = (client) => {
 			...patch.state !== void 0 ? { state: patch.state } : {},
 			...patch.base !== void 0 ? { base: patch.base } : {}
 		});
-		return yield* project(updated);
+		return yield* withMergeCommit(yield* project(updated));
 	});
 	return {
 		list,
@@ -215,7 +290,7 @@ const make = (client) => {
 				repo,
 				pull_number: number
 			});
-			return yield* project(raw);
+			return yield* withMergeCommit(yield* project(raw));
 		}),
 		listFiles: Effect.fn("PullRequest.listFiles")(function* (number, options) {
 			const { owner, repo } = yield* Repo;
@@ -242,7 +317,8 @@ const make = (client) => {
 				repo,
 				commit_sha: sha
 			}, options?.page);
-			return yield* Effect.forEach(raw, project);
+			const pulls = yield* Effect.forEach(raw, project);
+			return options?.mergeCommits === true ? yield* withMergeCommits(pulls) : pulls;
 		}),
 		upsert: Effect.fn("PullRequest.upsert")(function* (input) {
 			const found = (yield* list({

package/README.md

@@ -184,9 +184,13 @@ const program = Effect.gen(function* () {
     security_and_analysis: { secret_scanning: "enabled" },
   });
 });
-// AppliedSettings — { rest: [...], graphql: [...] }, in the caller's own key names.
-// The two lists agree with the input right up until preparation drops a field
+// AppliedSettings — { rest: [...], graphql: [...], ignored: [...] }, in the caller's own key names.
+// The lists agree with the input right up until preparation drops a field
 // GitHub would reject, which is what a person reading a dry run is checking for.
+// `ignored` names keys neither API accepts (a typo, say): they are never sent,
+// because the REST PATCH would ignore them and still answer 200. The REST key
+// list is generated from GitHub's OpenAPI description; a key a later
+// api-version removed is ignored only for a client pinned at or past it.
 ```
 
 `updateSettings` takes octokit's own generated params, and those spell an optional field as `has_issues?: boolean` rather than `has_issues?: boolean | undefined` — so under `exactOptionalPropertyTypes` a `Partial<T>` built from your own settings schema does not assign to it at all. `repositoryPatch` is the supported way out, and it exists so the answer is never a cast:
@@ -295,14 +299,14 @@ const TestClient = GitHubClient.layerFixture(fixtures);
 
 - `GitHubClient` — the typed transport: `request`, `requestDecoded` (a mandatory-schema escape hatch for routes outside the generated map), `paginate` / `paginateStream`, `graphql`, and `rateLimit` (observation only — nothing here throttles on your behalf).
 - `Repo` / `RepoRef` — the `{ owner, repo }` coordinate, resolved per call through `R`, with `Repo.provide` for multi-repository programs.
-- `GitHubRepository` — the repository's settings as GitHub's own generated type, plus `defaultBranch`, `nodeId`, `ownerType` for gating organization-only fields, and `applySettings` reporting the keys it actually sent.
+- `GitHubRepository` — the repository's settings as GitHub's own generated type, plus `defaultBranch`, `nodeId`, `ownerType` for gating organization-only fields, `applySettings` reporting the keys it actually sent, and `topics` / `setTopics(names)`, where `setTopics` replaces the whole set and returns what GitHub stored (lowercased).
 - `repositoryPatch` / `RepositoryPatchDraft` — build an `updateSettings` patch from fields that may be `undefined`, under `exactOptionalPropertyTypes`, without a cast.
 - `GitHubError` / `GitHubGraphQLError` — one error per transport, `kind`-routed with `hasKind` for `Effect.catchIf`; a REST 422's validation entries ride on `validation`, matched with `hasValidationCode`.
 - `RetryPolicy` — the client's one retry policy: full-jitter backoff, server-advised delays honored up to a ceiling.
 - `GitHubApp` — App JWT signing, installation token minting/revocation, app and installation identity, and `clientLayer` for an App-authenticated `GitHubClient`.
 - `GitBranch` / `GitTag` — Git Database API refs, with `upsert` collapsing the create-or-reset dance to one call and `GitTag.latestSemver` picking the newest version-shaped tag in one pass.
 - `CheckRun` — `withCheckRun` concludes on every exit path; `CheckRunOutput.truncated()` cuts rendered output to GitHub's byte limits.
-- `PullRequest` / `PullRequestComment` — upserts for both, `listFiles` answering with the same full `CommitFile` records a commit read returns, `headSha`/`baseSha` on `PullRequestInfo`, plus `CommentMarker` for finding a sticky comment again.
+- `PullRequest` / `PullRequestComment` — upserts for both, `listFiles` answering with the same full `CommitFile` records a commit read returns, `headSha`/`baseSha` on `PullRequestInfo`, plus `CommentMarker` for finding a sticky comment again. `PullRequestInfo.mergeCommitSha` is read from GraphQL `mergeCommit.oid` for merged pull requests only, because the REST object no longer carries it: `get`, `update` and `upsert` always fill it, while `list` and `listAssociatedWithCommit` fill it only with `mergeCommits: true` (one GraphQL call per 100 merged pull requests).
 - `GitHubIssue` — issues and their comments, including `commentOnce` for a marked comment that is posted exactly once and never edited, and `linkedIssues` for what a pull request closes.
 - `harvestIssueReferences` / `parseBareLineReference` — a compatibility re-export of the two closing-reference dialects that moved to `@effected/github-references`, with `CLOSING_KEYWORDS` and their result types.
 - `GitHubRelease` — releases and asset uploads, including the one route (`uploadAsset`, with the endpoint's optional display label) outside GitHub's generated endpoint map.

package/WorkflowDispatch.js

@@ -104,6 +104,8 @@ const DispatchResponse = Schema.Struct({
 });
 const decodeDispatchResponse = Schema.decodeUnknownEffect(DispatchResponse);
 const decodeDispatchedRun = Schema.decodeUnknownEffect(DispatchedRun);
+/** The api-version that reports the run unasked and removed `return_run_details`. */
+const RUN_DETAILS_BY_DEFAULT = "2026-03-10";
 const make = (client) => {
 	const dispatch = Effect.fn("WorkflowDispatch.dispatch")(function* (workflow, ref, inputs) {
 		const { owner, repo } = yield* Repo;
@@ -135,7 +137,7 @@ const make = (client) => {
 			workflow_id: workflow,
 			ref,
 			...inputs !== void 0 ? { inputs } : {},
-			return_run_details: true
+			...client.apiVersion < RUN_DETAILS_BY_DEFAULT ? { return_run_details: true } : {}
 		});
 		if (data === "" || data === null) return Option.none();
 		const run = yield* decodeDispatchResponse(data).pipe(Effect.flatMap((raw) => decodeDispatchedRun({

package/index.d.ts

@@ -761,7 +761,8 @@ export declare class PageOptions extends PageOptions_base {
  * Every member is an `Effect`, a `Stream`, or a function returning one — the
  * rule that keeps `Layer.mock` and `layerTest(Partial<Shape>)` useful. That
  * includes `rateLimit`, which is an `Effect`-valued property rather than a
- * getter for exactly this reason.
+ * getter for exactly this reason. The one plain value is `apiVersion`, a
+ * string fixed at construction that no double needs to stub.
  *
  * @public
  */
@@ -821,6 +822,20 @@ interface GitHubClientShape {
    * a caller that wants to pace itself proactively reads this.
    */
   readonly rateLimit: Effect.Effect<Option.Option<RateLimitSnapshot>>;
+  /**
+   * The REST api-version this client pins, as sent in `x-github-api-version`.
+   *
+   * @remarks
+   * A plain value, not an `Effect`: it is fixed when the client is built and
+   * reading it does no work. Resource services read it to shape a request for
+   * the version it goes out under — a body field one version requires and a
+   * later one removed, say. Calendar versions are `YYYY-MM-DD`, so two of them
+   * compare correctly as strings: `client.apiVersion < "2026-03-10"`.
+   *
+   * A call that sets its own `x-github-api-version` header goes out under that
+   * version instead; this is the version of every other call.
+   */
+  readonly apiVersion: string;
 }
 /**
  * How a client layer is built.
@@ -846,6 +861,25 @@ interface GitHubClientOptions {
    * a hand-written double of this service.
    */
   readonly fetch?: typeof globalThis.fetch | undefined;
+  /**
+   * The REST api-version every request pins, sent as `x-github-api-version`.
+   * Defaults to `"2026-03-10"`.
+   *
+   * @remarks
+   * Without the header GitHub serves its oldest supported version, which it
+   * deprecates and then sunsets, so the client always sends one. A call that
+   * sets its own `x-github-api-version` header keeps it: the per-call header
+   * wins over this option.
+   *
+   * A GitHub Enterprise Server release that predates the default version
+   * rejects the header, so a client pointed at one through `baseUrl` sets the
+   * newest version that server supports here.
+   *
+   * Must be a calendar version, `YYYY-MM-DD`. Anything else is a wiring
+   * mistake and kills the fiber building the client, with a defect naming
+   * this option, rather than reaching GitHub as a header it rejects.
+   */
+  readonly apiVersion?: string | undefined;
 }
 /**
  * One call served by {@link GitHubClient.layerFixture}, as recorded in
@@ -989,6 +1023,15 @@ export interface GitHubFixtures {
   readonly unstubbed?: "die" | "fail" | "empty" | undefined;
   /** What `rateLimit` answers. */
   readonly rateLimit?: RateLimitSnapshot | undefined;
+  /**
+   * What `apiVersion` answers; defaults to the live client's default,
+   * `"2026-03-10"`.
+   *
+   * @remarks
+   * Set it to drive a resource's version-dependent branch — a request body
+   * an older api-version needs — without a live client.
+   */
+  readonly apiVersion?: string | undefined;
   /**
    * Every call the fixture served, in order. Populated as the test runs.
    *
@@ -1065,11 +1108,14 @@ export declare class GitHubClient extends GitHubClient_base {
    * member **dies** naming itself.
    *
    * @remarks
-   * No member has an honest default. A fabricated response — an empty list, a
+   * No request member has an honest default. A fabricated response — an empty list, a
    * made-up sha — would leak into the code under test as fact, so the double
    * fails loudly instead, which also makes it proof that a test touches nothing
    * but what it stubbed.
    *
+   * `rateLimit` answers `Option.none()` and `apiVersion` the live default,
+   * because a real client legitimately answers both without a request.
+   *
    * For recorded responses that page for real, use
    * {@link GitHubClient.layerFixture}.
    */
@@ -1465,7 +1511,8 @@ interface AuthenticatedAppShape {
    *
    * @remarks
    * Irreversible from the app's side: only the account can install it again.
-   * An installation that does not exist (or is already gone) fails with
+   * GitHub answers 202 and removes the installation in the background, so it
+   * may still be listed briefly after this returns. An installation that does not exist (or is already gone) fails with
    * `GitHubError { kind: "notFound" }`.
    */
   readonly uninstall: (installationId: number) => Effect.Effect<void, GitHubError>;
@@ -1936,7 +1983,15 @@ export declare class CheckRun extends CheckRun_base {
 interface CodeScanningSetup {
   /** Whether default setup is `configured` or `not-configured`. */
   readonly state?: "configured" | "not-configured" | undefined;
-  /** The CodeQL languages to analyse. */
+  /**
+   * The CodeQL languages to analyse.
+   *
+   * @remarks
+   * CodeQL's names, not linguist's: JavaScript and TypeScript are the one
+   * combined `javascript-typescript`, and the separate `javascript` and
+   * `typescript` values are no longer accepted under the api-version the
+   * client pins.
+   */
   readonly languages?: ReadonlyArray<string> | undefined;
   /** `default` or `extended`. */
   readonly query_suite?: string | undefined;
@@ -2671,6 +2726,15 @@ interface GitHubAppOptions {
   readonly retry?: RetryPolicy | "off" | undefined;
   /** A replacement `fetch`, for tests and proxies. */
   readonly fetch?: typeof globalThis.fetch | undefined;
+  /**
+   * The REST api-version the app's clients pin; defaults to `"2026-03-10"`.
+   *
+   * @remarks
+   * The same option as `GitHubClientOptions.apiVersion`, applied to every
+   * client this module builds: as the app, as an installation, and
+   * unauthenticated.
+   */
+  readonly apiVersion?: string | undefined;
 }
 declare const GitHubApp_base: Context.ServiceClass<GitHubApp, "@effected/github/GitHubApp", GitHubAppShape>;
 /**
@@ -3600,17 +3664,21 @@ type OwnerType = "User" | "Organization";
  */
 export declare const SECURITY_ANALYSIS_STATUS_FIELDS: ReadonlySet<string>;
 /**
- * Settings reachable **only** through the GraphQL `updateRepository` mutation,
- * mapped from snake_case keys to camelCase GraphQL input fields.
+ * Settings written through the GraphQL `updateRepository` mutation, mapped
+ * from snake_case keys to camelCase GraphQL input fields.
  *
  * @remarks
- * GitHub never exposed these on the REST repository endpoint — the
- * `PATCH /repos/{owner}/{repo}` route accepts none of them, and
- * `has_discussions` is the treacherous one: the REST **read** returns it, so
- * routing its write to the PATCH looks symmetric, but the PATCH silently
- * ignores unknown body fields and answers 200, so the write would look applied
- * while the repository never changed. Setting any of these forces a second
- * round trip to learn the repository's node id.
+ * `applySettings` checks this map **first**, so a key here always goes
+ * through GraphQL, even when the REST patch also declares it.
+ * `has_sponsorships` and `has_discussions` are GraphQL-only: the
+ * `PATCH /repos/{owner}/{repo}` route accepts neither, and `has_discussions`
+ * is the treacherous one — the REST **read** returns it, so routing its write
+ * to the PATCH looks symmetric, but the PATCH silently ignores unknown body
+ * fields and answers 200, so the write would look applied while the
+ * repository never changed. `has_pull_requests` is in the REST patch's body
+ * too; GraphQL is preferred for it so the three toggles travel together.
+ * Setting any of these forces a second round trip to learn the repository's
+ * node id.
  *
  * @public
  */
@@ -3650,7 +3718,7 @@ export declare const transformSecurityAndAnalysis: (value: unknown) => Record<st
  * agree right up until a field is dropped, which is exactly the case anyone
  * reading a dry run is trying to check.
  *
- * Both lists use the **caller's** key names, not the wire names, because the
+ * Every list uses the **caller's** key names, not the wire names, because the
  * audience for them is a person reading a plan against the config they wrote.
  *
  * @public
@@ -3660,10 +3728,25 @@ interface AppliedSettings {
   readonly rest: ReadonlyArray<string>;
   /** Keys sent through the GraphQL mutation, named as the caller supplied them. */
   readonly graphql: ReadonlyArray<string>;
+  /**
+   * Keys neither API accepts, which were **not sent**.
+   *
+   * @remarks
+   * A key that is not a GraphQL-only setting and not in the REST patch's
+   * declared body — a typo such as `has_discussion`, or a setting GitHub has
+   * not described — lands here, as does a key the client's api-version
+   * removed from the patch (`use_squash_pr_title_as_default` under
+   * `2026-03-10` and later; a client pinned to an older version still sends
+   * it). Sending it would be worse than useless: the
+   * REST `PATCH` ignores unknown fields and answers 200, so the key would be
+   * reported applied while the repository never changed. A caller that wants
+   * an unknown key to fail the run checks this list.
+   */
+  readonly ignored: ReadonlyArray<string>;
 }
 /**
- * Read and update a repository's settings, and look up its default branch, node
- * id and owner type.
+ * Read and update a repository's settings and topics, and look up its default
+ * branch, node id and owner type.
  *
  * @public
  */
@@ -3709,30 +3792,58 @@ interface GitHubRepositoryShape {
    * `updateSettings` is the thin, faithfully-typed PATCH and returns what
    * GitHub then reports. This is the **applicator**: it takes an open map,
    * routes each key to whichever API can actually set it, and returns an
-   * {@link AppliedSettings} naming the keys that were sent through each.
+   * {@link AppliedSettings} naming the keys that were sent through each and
+   * the keys neither accepts.
    *
    * Three settings — `has_sponsorships`, `has_pull_requests` and
-   * `has_discussions` ({@link GRAPHQL_ONLY_SETTINGS}) — are only reachable
-   * through GraphQL's `updateRepository`, which addresses a repository by **node
-   * id**. So a map touching any of them costs an extra read; a map touching none
+   * `has_discussions` ({@link GRAPHQL_ONLY_SETTINGS}) — are written through
+   * GraphQL's `updateRepository`, which addresses a repository by **node id**;
+   * the first and last are reachable no other way, and GraphQL is preferred
+   * for `has_pull_requests`. So a map touching any of them costs an extra read; a map touching none
    * does not, which is the common case.
    *
    * The map is open by design. GitHub's settings surface is large and moving,
-   * and a closed type here would date the package — but it also means a typo is
-   * forwarded rather than rejected, so a caller that owns a schema should
-   * validate before calling.
+   * and a closed type here would date the package. A key that is neither
+   * GraphQL-only nor in the REST patch's declared body — the key list is
+   * generated from GitHub's OpenAPI description — is not sent and is reported
+   * in `ignored`, rather than forwarded to a `PATCH` that would ignore it and
+   * answer 200. It does not fail the call, so additive GitHub API growth never
+   * breaks a run; a caller that owns a schema should still validate first.
    */
   readonly applySettings: (settings: Record<string, unknown>) => Effect.Effect<AppliedSettings, GitHubError | GitHubGraphQLError, Repo>;
+  /**
+   * The repository's topics, as GitHub stores them.
+   *
+   * @remarks
+   * Reads `GET /repos/{owner}/{repo}/topics`, which answers the whole set in
+   * one object, so there is nothing to paginate. GitHub stores every topic
+   * lowercased, so this is the value to compare a desired set against.
+   */
+  readonly topics: Effect.Effect<ReadonlyArray<string>, GitHubError, Repo>;
+  /**
+   * Replace the repository's whole topic set, and return the set GitHub stored.
+   *
+   * @remarks
+   * `PUT /repos/{owner}/{repo}/topics` replaces rather than merges, so `names`
+   * is the complete desired set and an empty array clears every topic.
+   *
+   * **The return value is not `names`.** GitHub lowercases every topic it
+   * stores, so a caller that records what it sent — `Effect`, say — sees drift
+   * on the next read, which answers `effect`. Record the returned array, which
+   * is GitHub's own answer to the write, as the applied state.
+   */
+  readonly setTopics: (names: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<string>, GitHubError, Repo>;
 }
 declare const GitHubRepository_base: Context.ServiceClass<GitHubRepository, "@effected/github/GitHubRepository", GitHubRepositoryShape>;
 /**
  * Read and update a repository's settings, including settings only GraphQL can
- * write, and look up its default branch, node id and owner type.
+ * write, read and replace its topics, and look up its default branch, node id
+ * and owner type.
  *
  * @remarks
  * Provide it with {@link GitHubRepository.layer}, which needs a `GitHubClient`;
- * every member also needs a `Repo` in `R`. `settings`, `defaultBranch`, `nodeId`
- * and `ownerType` are `Effect` values, not functions.
+ * every member also needs a `Repo` in `R`. `settings`, `defaultBranch`, `nodeId`,
+ * `ownerType` and `topics` are `Effect` values, not functions.
  *
  * @example
  * ```ts
@@ -3743,7 +3854,7 @@ declare const GitHubRepository_base: Context.ServiceClass<GitHubRepository, "@ef
  *   const repository = yield* GitHubRepository;
  *   const branch = yield* repository.defaultBranch;
  *   const applied = yield* repository.applySettings({ has_wiki: false, has_discussions: true });
- *   return { branch, applied }; // applied.rest, applied.graphql
+ *   return { branch, applied }; // applied.rest, applied.graphql, applied.ignored
  * });
  * ```
  *
@@ -3919,7 +4030,27 @@ declare const PullRequestInfo_base: Schema.Class<PullRequestInfo, Schema.Struct<
   readonly mergedAt: Schema.Option<Schema.DateTimeUtcFromString>;
   /** The description, when GitHub sent one. */
   readonly body: Schema.optionalKey<Schema.String>;
-  /** The merge commit, once there is one. */
+  /**
+   * The sha of the commit the merge produced; absent until the pull request
+   * has merged.
+   *
+   * @remarks
+   * Read from GraphQL's `PullRequest.mergeCommit.oid`. The REST pull request
+   * object no longer carries `merge_commit_sha` under the api-version this
+   * package pins, so a merged pull request costs one extra GraphQL round trip
+   * per single read (`get`, `update`, `upsert`), and an open or
+   * closed-unmerged one costs nothing. When the REST response does carry the
+   * field (a client pinned to an older api-version), it is used for a merged
+   * pull request and the GraphQL read is skipped.
+   *
+   * **A list read leaves it absent unless asked.** `list` and
+   * `listAssociatedWithCommit` fill it only when called with
+   * `mergeCommits: true`, at one GraphQL call per 100 merged pull requests.
+   *
+   * It is never the speculative test-merge commit GitHub computes for an open
+   * pull request, so `mergeCommitSha === sha` means "this commit is what the
+   * pull request merged as".
+   */
   readonly mergeCommitSha: Schema.optionalKey<Schema.String>;
 }>, {}>;
 /**
@@ -3953,7 +4084,7 @@ interface UpsertedPullRequest {
  */
 interface PullRequestShape {
   /** Read one pull request. Fails `notFound` when it does not exist. */
-  readonly get: (number: number) => Effect.Effect<PullRequestInfo, GitHubError, Repo>;
+  readonly get: (number: number) => Effect.Effect<PullRequestInfo, GitHubError | GitHubGraphQLError, Repo>;
   /**
    * Open, closed or all pull requests, optionally filtered.
    *
@@ -3970,13 +4101,20 @@ interface PullRequestShape {
    * in the wrong account — the filter then matches nothing, silently. When the
    * head may live in a fork, pass a qualified `owner:ref` built from the source
    * owner rather than from anything this projection carries.
+   *
+   * **`mergeCommitSha` is absent on every result unless `mergeCommits` is
+   * `true`.** The REST list no longer carries it, and filling it costs one
+   * GraphQL call per 100 merged pull requests in the result, so it is opt-in.
+   * Only with the option can this fail with `GitHubGraphQLError`.
    */
   readonly list: (options?: {
     readonly head?: string | undefined;
     readonly base?: string | undefined;
     readonly state?: "open" | "closed" | "all" | undefined;
     readonly page?: PageOptions | undefined;
-  }) => Effect.Effect<ReadonlyArray<PullRequestInfo>, GitHubError, Repo>;
+    /** Fill `mergeCommitSha` on merged results from GraphQL. Defaults to `false`. */
+    readonly mergeCommits?: boolean | undefined;
+  }) => Effect.Effect<ReadonlyArray<PullRequestInfo>, GitHubError | GitHubGraphQLError, Repo>;
   /**
    * The files a pull request changes.
    *
@@ -3994,10 +4132,17 @@ interface PullRequestShape {
    *
    * @remarks
    * Paginated: pass `page` to bound the walk.
+   *
+   * **`mergeCommitSha` is absent on every result unless `mergeCommits` is
+   * `true`**, at one GraphQL call per 100 merged pull requests — so a caller
+   * matching `sha` against the merge commit passes it. Only with the option
+   * can this fail with `GitHubGraphQLError`.
    */
   readonly listAssociatedWithCommit: (sha: string, options?: {
     readonly page?: PageOptions | undefined;
-  }) => Effect.Effect<ReadonlyArray<PullRequestInfo>, GitHubError, Repo>;
+    /** Fill `mergeCommitSha` on merged results from GraphQL. Defaults to `false`. */
+    readonly mergeCommits?: boolean | undefined;
+  }) => Effect.Effect<ReadonlyArray<PullRequestInfo>, GitHubError | GitHubGraphQLError, Repo>;
   /** Open a pull request from `head` into `base`. */
   readonly create: (input: {
     readonly title: string;
@@ -4012,7 +4157,7 @@ interface PullRequestShape {
     readonly body?: string | undefined;
     readonly state?: "open" | "closed" | undefined;
     readonly base?: string | undefined;
-  }) => Effect.Effect<PullRequestInfo, GitHubError, Repo>;
+  }) => Effect.Effect<PullRequestInfo, GitHubError | GitHubGraphQLError, Repo>;
   /**
    * Update the open pull request for `head`→`base`, or open one.
    *
@@ -4026,7 +4171,7 @@ interface PullRequestShape {
     readonly base: string;
     readonly body?: string | undefined;
     readonly draft?: boolean | undefined;
-  }) => Effect.Effect<UpsertedPullRequest, GitHubError, Repo>;
+  }) => Effect.Effect<UpsertedPullRequest, GitHubError | GitHubGraphQLError, Repo>;
   /** Merge a pull request and return the merge commit sha. `method` defaults to GitHub's choice. */
   readonly merge: (number: number, options?: {
     readonly method?: "merge" | "squash" | "rebase" | undefined;
@@ -4704,15 +4849,21 @@ interface WorkflowDispatchShape {
    * Fire a `workflow_dispatch` event and report the run it created.
    *
    * @remarks
-   * Sends the same request as {@link WorkflowDispatchShape.dispatch} with
-   * `return_run_details: true`. GitHub then answers 200 with the run's id and
-   * URLs, which arrive as `Option.some` of a {@link DispatchedRun}; a 200 body
-   * that does not have that shape fails with a `decode` `GitHubError`.
-   *
-   * A 204 with no body is `Option.none()`. That is what a GitHub Enterprise
-   * Server predating the field answers — it ignores `return_run_details` and
-   * still dispatches — so it is **not a failure**: the workflow was dispatched,
-   * the server just did not say which run it created.
+   * Sends the same request as {@link WorkflowDispatchShape.dispatch}. Under
+   * the api-version the client pins by default, GitHub answers every dispatch
+   * with 200 and the run's id and URLs, which arrive as `Option.some` of a
+   * {@link DispatchedRun}; a 200 body that does not have that shape fails with
+   * a `decode` `GitHubError`.
+   *
+   * A 204 with no body is `Option.none()`. That is what an older api-version
+   * answers when it does not report the run — a GitHub Enterprise Server that
+   * predates the field, say — and it is **not a failure**: the workflow was
+   * dispatched, the server just did not say which run it created.
+   *
+   * Older api-versions report the run only when asked, so a client pinned
+   * before `2026-03-10` (`GitHubClientShape.apiVersion`) sends
+   * `return_run_details: true`; from `2026-03-10` on the flag is removed from
+   * the request and is not sent.
    *
    * Under `GitHubClient.layerFixture`, stub the 204 the way every other
    * no-body route is stubbed: answer the dispatch route with `null`. `""`
@@ -4762,8 +4913,8 @@ interface WorkflowDispatchShape {
    *
    * The run is identified by {@link WorkflowDispatchShape.dispatchWithRun}:
    * when GitHub reports the run it created, exactly that run is polled, so
-   * concurrent dispatches cannot be confused. When it does not (a 204 from a
-   * GitHub Enterprise Server predating `return_run_details`), the run is found
+   * concurrent dispatches cannot be confused. When it does not (a 204 from an
+   * older api-version), the run is found
    * instead by branch, creation time and workflow path — and on that fallback
    * alone, concurrent dispatches of the same workflow on the same ref can be
    * confused.

package/internal/octokit.js

@@ -6,6 +6,8 @@ import { Octokit } from "@octokit/core";
 import { composePaginateRest } from "@octokit/plugin-paginate-rest";
 
 // src/internal/octokit.ts
+/** The REST api-version a client pins when its options name none. */
+const DEFAULT_API_VERSION = "2026-03-10";
 const SILENT_LOG = {
 	debug: () => {},
 	info: () => {},
@@ -25,13 +27,19 @@ const SILENT_LOG = {
 * maps Effect's logs to whatever its runtime wants, so no GitHub Actions
 * knowledge lives in this client.
 */
-const makeOctokit = (options) => new Octokit({
-	...options.token !== void 0 ? { auth: Redacted.value(options.token) } : {},
-	...options.baseUrl !== void 0 ? { baseUrl: options.baseUrl } : {},
-	...options.userAgent !== void 0 ? { userAgent: options.userAgent } : {},
-	...options.fetch !== void 0 ? { request: { fetch: options.fetch } } : {},
-	log: SILENT_LOG
-});
+const makeOctokit = (options) => {
+	const octokit = new Octokit({
+		...options.token !== void 0 ? { auth: Redacted.value(options.token) } : {},
+		...options.baseUrl !== void 0 ? { baseUrl: options.baseUrl } : {},
+		...options.userAgent !== void 0 ? { userAgent: options.userAgent } : {},
+		...options.fetch !== void 0 ? { request: { fetch: options.fetch } } : {},
+		log: SILENT_LOG
+	});
+	octokit.hook.before("request", (request) => {
+		request.headers["x-github-api-version"] ??= options.apiVersion;
+	});
+	return octokit;
+};
 /**
 * Build a transport over a freshly constructed octokit instance.
 *
@@ -105,4 +113,4 @@ const readThrownHeaders = (error) => {
 	return typeof headers === "object" && headers !== null ? headers : void 0;
 };
 
-export { makeTransport };
+export { DEFAULT_API_VERSION, makeTransport };

package/internal/repositoryRestSettingKeys.js

@@ -0,0 +1,44 @@
+// src/internal/repositoryRestSettingKeys.ts
+/**
+* Every key the REST repository PATCH accepts, as GitHub's OpenAPI description declares it.
+*
+* @internal
+*/
+const REPOSITORY_REST_SETTING_KEYS = /* @__PURE__ */ new Set([
+	"allow_auto_merge",
+	"allow_forking",
+	"allow_merge_commit",
+	"allow_rebase_merge",
+	"allow_squash_merge",
+	"allow_update_branch",
+	"archived",
+	"default_branch",
+	"delete_branch_on_merge",
+	"description",
+	"has_issues",
+	"has_projects",
+	"has_pull_requests",
+	"has_wiki",
+	"homepage",
+	"is_template",
+	"merge_commit_message",
+	"merge_commit_title",
+	"name",
+	"private",
+	"pull_request_creation_policy",
+	"security_and_analysis",
+	"squash_merge_commit_message",
+	"squash_merge_commit_title",
+	"use_squash_pr_title_as_default",
+	"visibility",
+	"web_commit_signoff_required"
+]);
+/**
+* Keys in {@link REPOSITORY_REST_SETTING_KEYS} that an api-version removed,
+* mapped to that version: a client at or past it does not send the key.
+*
+* @internal
+*/
+const REMOVED_BY_PINNED_VERSION = { use_squash_pr_title_as_default: "2026-03-10" };
+
+export { REMOVED_BY_PINNED_VERSION, REPOSITORY_REST_SETTING_KEYS };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/github",
-	"version": "0.24.0",
+	"version": "0.25.0",
 	"private": false,
 	"description": "Typed GitHub REST and GraphQL services over the octokit core request surface, with app auth and resource helpers.",
 	"keywords": [
@@ -41,7 +41,7 @@
 		"@effected/github-references": "^0.11.0",
 		"@effected/jwt": "^0.6.0",
 		"@effected/oidc": "^0.1.2",
-		"@effected/semver": "^0.17.0",
+		"@effected/semver": "^0.18.0",
 		"@octokit/core": "^7.0.6",
 		"@octokit/plugin-paginate-rest": "^16.0.0",
 		"@octokit/types": "^18.0.0",