chore(main): release 3.0.0

[github-actions]

🤖 I have created a release beep boop

3.0.0 (2026-09-23)

⚠ BREAKING CHANGES

• release: publish next from the release-PR hook and drop the post-green verdict
• github: GitHubClient.tryRequest() and tryGraphql() resolve to ClientAnswer, whose third arm is { failed }, and ArtifactUploader.upload() resolves to { uploaded: true } | { failed }. docs/upgrading/v2-to-v3.md section 58 names the fix.
• engine: CheckOptions and ApplyOptions lose secretSource; pass it to validateSettings. A literal secret value in a section the sections input excludes now fails validation with exit 1 and zero requests.
• sections: SectionModule.plan() and snapshot() resolve to Result<..., SectionFailure> instead of the plan or snapshot; docs/upgrading/v2-to-v3.md section 56 names the fix.
• engine: a higher layer's null no longer deletes a lower key; it is written as the value, and a null a key does not admit fails validation naming the legal values. Drop a keyed entry with _remove: true, or clear a list with _layering: replace.
• library: SectionModule.plan() no longer accepts a raw section value. Pass the section off a validated document: validateSettings(doc) (or mergeSettings, or snapshotRepository) returns settings, and settings.labels is the ValidatedInput<"labels"> that labels.plan() takes.
• engine: the problem codes settings-unknown-directives and settings-unknown-sections are deleted; settings-malformed-sections carries their lines in its issues. A switch on Problem.code naming either code stops compiling; drop the case.
• engine: a settings file whose excluded sections carry a declaration the file-only checks refuse (duplicates, malformed lists, an unreadable deploy key) now fails before any write, naming the path; fix the declaration. A custom list module built with the library implements the validate hook.
• repository: a repository section declaring a GET-only key (has_downloads, has_pages, custom_properties, ids, urls, counts), an unknown security_and_analysis sub-key, a commit message without its title or in an illegal squash pair, a malformed topic, or a PATCH toggle as null or a quoted boolean (has_wiki: "true", has_wiki: with no value) now fails to parse; the error names the key and the fix.
• branches: a branches entry whose protection.restrictions mapping omits users or teams no longer parses; declare both lists ([] when none), or restrictions: null to lift the push restriction.
• rulesets: a rulesets entry fails at parse, before any request, when its enforcement is not active, evaluate, or disabled; when a bypass actor breaks the spec's actor_id or bypass_mode rules; when ref_name carries "~" outside ~ALL or ~DEFAULT_BRANCH or a character git refuses in a ref name ("^", ":", "", space, "..", "@{", control characters); or when a known rule type carries parameters the spec rejects. The message names the entry, key, and accepted values. An unknown rule type still passes through.
• deploy-keys: a deploy_keys[].key that is not one line of <algorithm> <base64> [comment] with the algorithm one of ssh-ed25519, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, sk-ssh-ed25519@openssh.com, sk-ecdsa-sha2-nistp256@openssh.com now fails the settings-file parse (a DSA key is refused naming the date GitHub dropped DSA), and a pasted private key is refused there without the material being echoed; declare the contents of the .pub file.
• engine: a higher layer's environments, branches, or workflows no longer replaces the lower list under the default layering: deep; write _layering: replace on the section's wrapper, or layering: replace on the run, to keep the old outcome.
• secret-scanning: a secret_scanning_custom_patterns entry whose pattern, start_delimiter, end_delimiter, must_match, or must_not_match value fails the syntax check now fails the run at parse with exit 1, naming the field; previously it reached GitHub's bulk create.
• rulesets: the parsed SettingsFile ruleset entry (the one sectionModule("rulesets").plan takes) requires target and enforcement, so a typed literal without them fails to compile. Parse the document through validateSettings, or declare both keys.
• branches: a required_status_checks.checks item with a key other than context or app_id is refused; remove the key.
• branches: a settings file declaring required_status_checks without strict or without contexts/checks, a required_approving_review_count outside 0-6, a scalar where those two mappings go, a GET-only protection key (name, enabled, enforcement_level, url, *_url at any depth), or an actor object where restrictions, dismissal_restrictions, or bypass_pull_request_allowances take login/slug strings now fails to parse before any request; the error names the key and the fix.
• check-suite-preferences: check_suite_preferences.auto_trigger_checks[].app_id must be a positive integer and may appear once; a settings file carrying 0, a fraction, or a repeated app_id now fails at parse with a message naming the entries and the fix.
• setup: a settings file declaring schedule, updated_at, a language in the GET's spelling (javascript, typescript, rust), or a string runner_label without runner_type: labeled now fails to parse with a message naming the fix.
• actions: a settings file that declares selected_actions_url, artifact_and_log_retention.maximum_allowed_days, oidc_customization_sub.sub_claim_prefix, a selected_actions key outside the three documented ones, a mistyped selected_actions value (github_owned_allowed: "true", patterns_allowed: "docker/*"; main's record of unknown values accepted them), sha_pinning_required as a string ("true"; main passed it through as an undeclared key), an approval_policy outside GitHub's three, a malformed or repeated OIDC claim key, include_claim_keys beside use_default: true, or a fractional or non-positive retention or cache limit now fails to parse before any request; the error names the key and the fix.
• sections: a settings file that omits a live field of a declared ruleset or environment now fails apply instead of writing over it; declare the field to keep the value, or declare it empty (bypass_actors: [], reviewers: [], deployment_branch_policy: null) to remove it on purpose
• engine: _layering: merge and layering: merge no longer exist and fail as unknown values (the set is replace, shallow, deep). mode: merge is mode: render, merged-file is rendered-file, the CLI subcommand merge is render, the result word merged is rendered, and the problem codes input-merge-only, input-rejected-in-merge, input-merged-file-missing, merged-file-is-layer, and merged-file-unwritable carry the render spelling. Every list section now unions by its key under the default, where only labels and rulesets did.
• secrets: a settings file whose secret or variable name has a hyphen, a space, a leading digit, or a GITHUB_ prefix in any case, or whose variable value is over 49152 bytes of UTF-8, now fails to parse before any request instead of reaching GitHub. Rename the entry to ASCII letters, digits, and underscores, or shorten the value; the problem line names the entry's path.
• sections: collaborators[].permission and teams[].permission refuse "read", "write", mis-cased standard permissions, empty values, and whitespace at either end; declare "pull", "push", or the lowercase form. teams[].name refuses anything outside [A-Za-z0-9._-] and a value with no letter or digit; declare the team's slug.
• webhooks: a settings file whose webhook names an event GitHub does not deliver to repository webhooks, a content_type other than "json" or "form", an insecure_ssl other than "0", "1", 0, or 1, or a url that is not an absolute URL now fails to parse with exit 1 instead of failing at apply time.
• interaction-limits: interaction_limits accepts only limit, expiry, pull_request_creation_cap, and pull_request_creation_bypass; limit and expiry must be GitHub's enum values and max_open_pull_requests a whole number from 1 to 1000. A settings file carrying anything else now fails at parse with a message naming the key and the rule.
• pages: a pages declaration carrying url, html_url, status, custom_404, protected_domain_state, pending_domain_unverified_at, or https_certificate fails validation before any request; remove the key. pages.source.path accepts only / or /docs; any other path fails validation before any request.
• milestones: due_on takes a calendar day YYYY-MM-DD (or a UTC timestamp YYYY-MM-DDTHH:MM:SSZ, read for its day); due_on: null and offset timestamps such as 2026-01-15T00:00:00+02:00 are refused with an error naming the day form. A snapshot emits a due date as YYYY-MM-DDT12:00:00Z.
• labels: labels[].color must be six hex digits with the leading "#" optional, and labels[].description is capped at 100 characters; a settings file carrying either now fails at parse with a message naming the entry and the rule.
• engine: a higher pages: null now means "site off". A repository that used pages: null over a fleet Pages block to opt out of the fleet's declaration has its live Pages site deleted on the next apply, and interaction_limits: null over a fleet limit clears the live limit the same way. The way to opt out of a fleet Pages block without disabling the site no longer exists.
• environments: environment declarations that parsed before are refused at parse time: wait_timer outside 0..43200 or not an integer, more than six reviewers, deployment_branch_policy with both flags true or both false, prevent_self_review without reviewers, and a deployment_branch_policies type outside branch and tag; the exported DeploymentBranchPolicyConfig.type narrows to "branch" | "tag". A fractional wait_timer (2.5): write a whole number of minutes. prevent_self_review: true without reviewers: declare a reviewer, or write prevent_self_review: false. deployment_branch_policy with both flags false: write deployment_branch_policy: null. deployment_branch_policies[].type outside branch | tag (wildcard): write branch or tag.
• sections: a GET or GraphQL body off GitHub's documented shape now fails the section with returned a body outside the documented shape naming the endpoint and field, where before it flowed into the comparison or a section's own message; a reading section without snapshot() no longer compiles; the teams and custom_properties owner probe runs ahead of their own validation.
• sections: teams, workflows, the environment listing and its pins, the protected-branch listing, the GraphQL protection rules, and the protection-rule Apps now fail plan and snapshot when GitHub holds two items under one identity, naming both; before, one was picked silently. The protection-rule Apps list is read at plan for an existing environment and after the PUT for one the run creates.
• sections: the teams, collaborators, and inherited interaction-limit snapshot notes read <label>: left out of the snapshot - <reason>; the interaction_limits.expiry and repository toggle notes use the cannot-verify template; a personal account under teams or custom_properties reads one note (docs/upgrading/v2-to-v3.md section 13).
• library: the merged file is the fold in the layers' key order, so a merged file committed under v2 reorders once. A top-level null on a section nothing below declares drops without a notice (pages and interaction_limits keep it), where v2 refused the merge.
• flows: parseConfig(read, env, capabilities) owns the private-report: artifact refusal (input-artifact-unsupported); artifact-uploader-missing and the flows' uploader check are gone. executeRun returns RunEnd { exitCode, fatal? } and RunDeps has no describe; failRun(io, problem) takes no wording hook. validateSettingsDoc and validateSettings take a SectionSelection where they took a ReadonlySet<SectionKey>. parseSnapshotFileConfig(read, env, "settings-file") reads the destination itself; SettingsFileRole gains central-file. The action and the command line print one wording per problem; remedies name the input and its flag and say "re-run" without "the workflow".
• release: the build branch gets nothing new and is deleted once every consumer has repinned; packaged commits live under build/. tags, the ten newest kept, so a sha pinned from one lives until ten newer commits are packaged. A rerun of an older release's retag-major leaves a newer release's major in place instead of failing; the verify subcommand is gone.
• sections: check mode no longer reads a secret family's sealing key (a malformed key fails the first PUT at apply); the environment secret and variable lines use the engines' wording (docs/upgrading/v2-to-v3.md sections 19-20).
• settings: an unknown underscore key at the document root fails validation naming _layering and _undeclared, where v2 dropped it as a private note; move notes into YAML comments. teams takes the {_undeclared, entries} wrapper (default keep): every run lists the repository's teams (repository Administration read) and notes undeclared direct grants, _undeclared: delete revokes them, and snapshots write the wrapper form. The retry-timing knob is read from GSAC_RETRY_BASE_MS; RETRY_BASE_MS is ignored.
• sections: two live items under one identity fail every list section, in plan and snapshot; the webhook snapshot placeholder is $SECRET_WEBHOOK_; webhooks manage web hooks only and never write name; a ruleset without source_type is repository-owned, a repeated rule type a settings-file error; one wording per concept in drift lines and notes (docs/upgrading/v2-to-v3.md sections 11-15).
• library: the npm library's entry exports the 118 documented names; 88 of its v2 names leave it: 83 move to the ./internal subpath with no semver promise and 5 are renamed below. GithubApi, GithubApiOptions, GithubClient are GitHubApi, GitHubApiOptions, GitHubClient; MissingPermissionPolicy is OnMissingPermission. checkRepository and applyRepository take (client, repo, settings, options?); RepoRunReport is CheckReport and ApplyReport; SnapshotLibraryOptions is SnapshotOptions. validateSettings returns { settings, log } and takes sections as a SectionSelection; mergeSettings(layers, options?) replaces the public foldLayers.
• flows: one redaction seal for every target kind (#204)
• flows: one run outcome model for every mode (#201)
• upgrading: two more v3 breaks. (1) A settings-file path may no longer contain a comma or a newline in any mode (they are the list separators mode: merge splits on); apply and check reject such a path with an input error naming the rule; rename the file. (2) defaults-file is no longer merged under every multi-repo target: it is applied whole to a target that has no settings file of its own (previously skipped), and a target's own file is applied as written; build layered documents with mode: merge and apply its output; run mode: check first, since with repos: "*" every discovered repository without a settings file now receives the defaults.
• the knobbed list wrapper's policy key is _undeclared; a settings file still writing undeclared fails validation with an error naming the new key.

Features

• actions: refuse at parse the actions fields that could never converge (f68d78b)
• add mode: merge with a layered settings-file (#104) (d50e70b)
• add the plan-returning section contract and migrate the workflows section (8a65765)
• branches: refuse protection shapes the settings file alone shows wrong (990c51a)
• check-suite-preferences: refuse app_ids GitHub rejects or collapses when the file is parsed (5b3c8e9)
• ci: gate kept backward-compatibility code behind COMPAT markers (#173) (bf9f482)
• ci: never-throw gate with a shrinking ratchet in lint:arch (8fcc505)
• cli: github-settings-as-code and gsac commands over the library (#152) (364a9c6)
• cli: gsac init writes the live settings to .github/settings.yml and prints its PAT grant (#178) (3fad2b2)
• cli: under GitHub Actions the CLI emits the action's workflow commands (#223) (de75a22)
• contract: extend the plan contract for every migrating section (9ae375c)
• deploy-keys: refuse anything but a public SSH key at parse (473aa1a)
• derive list sections from a declarative factory, piloted on labels (71859b5)
• engine: a higher layer's null wins and means empty on GitHub, and _remove drops a keyed entry (2ae92c5)
• engine: a higher-layer null keeps its value on pages and interaction_limits (6154cc5)
• engine: layer environments, branches, and workflows by key through a {_layering, entries} wrapper (9e52313)
• engine: layer every list section by key with replace, shallow, and deep (8133147)
• engine: report every parse error of a section in one run (db7ebec)
• engine: resolve the undeclared policy once from a file-wide _undeclared and the undeclared input (a9dcf68)
• engine: run every file-only check before the first write (1bbe9b2)
• environments: declared-off protection converges, and the schema refuses what GitHub never accepts (aa43d3e)
• generate action.yml, the inputs table, and the policy and permissions references from declarations (d062cf1)
• generate COVERAGE.md from section declarations (51068cd)
• generate the README sections table, outputs, and PAT form from section declarations (83f3c84)
• interaction-limits: refuse limits, expiries, caps, and keys GitHub rejects when the file is parsed (1e9a806)
• labels: refuse colors and descriptions GitHub rejects when the file is parsed (10242f4)
• library: export the section contexts so a consumer can call a section module directly (#191) (ed6143a)
• library: package @vivswan/github-settings-as-code (#142) (cbeb56f)
• library: plan() takes only the input validation minted (ce31e10)
• pages: refuse the site fields only the GET reports and a source path Pages cannot publish from (3f17468)
• publish packaged commits on a build branch, with latest and the version tags on it (#122) (db45c7d)
• release: carry the library build on the packaged branch and publish to npm (#150) (8eb5897)
• release: publish next from the release-PR hook and drop the post-green verdict (006e276)
• render: the snapshot and the merged file render one canonical order, and the snapshot carries no timestamp (#237) (9d16e15)
• report: a delivered report issue is announced in the log (#235) (7e85572)
• repository: refuse GET-only keys, illegal commit-message pairs, bad topics, and unknown security sub-keys at parse (82429e1)
• rulesets: refuse what the file alone shows wrong about a ruleset when it is parsed (50959dd)
• secret-scanning: refuse patterns that cannot compile when the file is parsed (3c81fa2)
• secrets: refuse secret and variable names GitHub rejects when the file is parsed (6f93110)
• sections: refuse permissions and team names GitHub rejects when the file is parsed (830d0a8)
• setup: refuse known-wrong setup keys at parse and note unechoed keys (562d6f0)
• snapshot: branches and environments read back (#147) (5f03322)
• snapshot: collaborators and teams read back (#148) (3b4f753)
• snapshot: mode snapshot writes live settings to a file or a per-repo directory (#146) (9233a14)
• snapshot: read back the GraphQL-only branch rules and environment pins (#185) (63435fc)
• snapshot: repository, actions, and rulesets read back (#143) (3d256b8)
• snapshot: section snapshot contract, engine, round-trip harness, and the first sections (#140) (f721bb1)
• webhooks: derive the repository event vocabulary from GitHub's webhooks OpenAPI description (a3ca9c8)
• webhooks: refuse events, content types, insecure_ssl spellings, and urls GitHub would 422 (4414231)

Bug Fixes

• action: the YAML parser never prints a settings file's source lines as warnings (#123) (54a50a0)
• adopt zod 4.5's native root $ref emission and own-proto rejection (#67) (44dab3b)
• apply review fixes to the docs and tooling sweep (73b6b4a)
• apply review fixes to the harness audit batch (ceb9f46)
• apply review fixes to the src-side audit batch (b9de617)
• attest build provenance and attach the sigstore bundle to releases (b5db672)
• autolinks: keep the live is_alphanumeric on a recreate and refuse what GitHub 422s (#263) (2011455)
• branches: a denied branch probe no longer reads as a missing branch (#149) (c1d6243)
• branches: compare actor lists case-insensitively and read an absent review holder as empty (#269) (46ed70f)
• branches: refuse a restrictions block without its users and teams lists at parse (03f783e)
• branches: report an omitted all-empty live restrictions holder and type required_status_checks.checks items (917025c)
• branches: seal GraphQL node-id lookups at execution so check mode never issues them (#75) (feaf279), closes #73
• centralize the token-leak sweep in the runner (7dcc225)
• ci: name the fuzz-issue inputs the action no longer defaults (#186) (fded5f5)
• classify rate limits structurally on every path (65f97a2)
• cli: each command's help names only the flags it accepts (#182) (51a75e7)
• contract: classify definitive 404 rejections ahead of the permission branch (#164) (8be6b7d)
• contract: the plainData refusal names what JSON does with each bad item; the grant comment points at the generated docs; the validate truncation arms get their relation (#231) (0118807)
• correct mock identity minting and the pages resurrect bug (9152a91)
• cover every faultable section in the fuzz fault battery (e41aa99)
• derive owner-kind sensitivity from the section declaration (0181f01)
• dev: a fresh checkout runs bun run check green; the trimmed OpenAPI file regenerates when absent (#219) (7468741)
• discover schema-corpus scenarios across all scenario roots (d34d031)
• e2e: oracle never predicts a preflight abort for teams on a personal account (#114) (152c7d9)
• e2e: path param accessors read own keys only (#158) (89c8ee8)
• engine: judge secret references at validation, in excluded sections too (bc0d7f6)
• engine: the validated brand has one mint; the marker injection re-validates (df18966)
• engine: withhold a secret-carrying request's failure for any client (#175) (14a5c72)
• every count in a user-facing message takes the singular or the plural, never "(s)" (#236) (5523d38)
• flows: the fleet summary says one repository; a duplicate private target is deduped under its redacted name (#233) (d23fea1)
• github: keep the throttling plugin on under the test knob via an injected scheduler (#161) (dbdcd7b)
• github: pace every throttling group by the client's own scheduler (#165) (d70d315)
• github: refuse a cyclic payload at its field instead of exhausting the stack (#171) (9dc8e42)
• hand sections the parsed settings document instead of the raw one (1ddc2f3)
• harden release boundary checks and decouple the schema id from the release manifest (f5c4c59)
• harden the CI tooling (6fb2603)
• io: collectingIo masks captured text with the shared redactor (#163) (a0faf1c)
• keep spec-pinned gaps out of automatic graduation (ae278c9)
• layers: a validation issue after a _remove entry names the entry by its index in the file (5b4b750)
• library: gate findings on the packaging PR (#156) (e4e8b4c)
• library: mergeSettings renders the fold the action writes; a null over nothing drops (e725c08)
• milestones: compare due_on by day so it converges (c02395c)
• nightly: file the curated e2e issue through the fleet action (#160) (8ef9747)
• nightly: replay a fuzz artifact with the command its run wrote (#157) (339e002)
• parse live bodies through parseLive in the seven asserting sections (56ca3e4)
• pass zod's schema layout through instead of guarding it (#68) (64aad27)
• reject required-sections entries excluded by the sections allowlist (c1fc169)
• release: follow the attestation bundle rename in the repo-owned asset check and SECURITY.md (#76) (3704176)
• release: keep next from moving back on a publish the registry has not yet shown (#190) (c247bab)
• release: order pre-release versions by main's commit count, not the run number (#197) (131780e)
• release: read the major line in one advertisement and publish latest from the whole chain (#172) (1312f3f)
• release: refuse a build tip whose Source trailer is not a full sha and fix the post-green coalescing note (#176) (ee6c725)
• report: match report issues by their own body, open over closed, newest first (#170) (8d5c1a8)
• report: paginate the report-issue lookups and scan by title, not creator (#159) (631e1da)
• rulesets: bypass_actors hidden from a non-admin token is not drift (#137) (b8df084)
• scripts: the permission count in the generated docs takes the helper; the npm-confirm line is pinned with an injectable pause (#239) (e6897d8)
• sections: every shape rule reports beside a raw sibling instead of ending on it (e1c62bd)
• sections: make the impossible literal-with-routed-keys branch entry unrepresentable and declare the sealing-key read's phase (#195) (95d081d)
• sections: note unknown keys on the protection PUT and the routed actions mappings at check time (56a0809)
• sections: note unknown pages keys at check time and accept Hyperscan start verbs (899455f)
• sections: report live values the full-payload write would drop, and refuse to apply over them (62b27c0)
• sections: require the deploy key read_only flag, carry the label brands through the list section, deep-freeze the registries (#187) (15ef0c9)
• sections: undeclared deletes before creates, a lens wire hook for the request body, one boundedString cap helper (9675999)
• settings: resolve YAML merge keys in the settings reader (#262) (8977aea)
• settings: unknown underscore keys fail everywhere; teams gets the _undeclared knob; GSAC_RETRY_BASE_MS (05e6d41)
• single-tag releases - version tags live only on packaged commits (08d5585)
• size the harness kill cap for the directed fuzz battery (8543af8)
• snapshot: a denied sub-read fails the section under on-missing-permission: fail (#184) (04d8d35)
• snapshot: refuse a destination the filesystem carries onto an authored file (#179) (5b24963)
• strengthen the remaining per-section representations (3fc0f85)
• test: match private-report heading markers without an HTML-comment regex (#106) (33ff405)

Documentation

• upgrading: link the v3 breaks to their guides (8541b3d)

Miscellaneous Chores

• drop the release-as pin and the machinery that retired it (a2cc999)

Code Refactoring

• flows: one owner per refusal, read, and write; one wording for both faces (bd9b6dd)
• flows: one redaction seal for every target kind (#204) (f1f938e)
• flows: one run outcome model for every mode (#201) (033a9c6)
• github: the client answers instead of throwing, and the ratchet reaches zero (d52d4bb)
• library: a documented public entry and an internal one; one naming family per layer (d92b738)
• release: one immutable packaged commit per main sha; latest and vN move only forward; the build chain retires (eac7de6)
• rulesets: fill target and enforcement at parse so an entry may omit them (0adf417)
• sections: environments plan through the secrets and variables engines; the sealing key is read at apply (5dfc10a)
• sections: milestones, webhooks, and rulesets join listSection; duplicate live items fail loudly everywhere (2cb5c8a)
• sections: one duplicate-live guard and identity rendering over every live list (f7c72ff)
• sections: one helper per repeated concept; the snapshot notes teams and collaborators leave out use the shared template (aa1f86f)
• sections: section plans return Results instead of throwing (7ede2bc)
• sections: the read port parses every live body, and the registry owns the owner probe (cb772c5)

---

This PR was generated with Release Please. See documentation.