Guides

The documentation for GitHub Settings as Code, in five groups. Start here if the README told you what the action does and you want to know how to put it to work: the start pages are enough to get a repository under management, and the rest are there when their topic comes up.

Pick by goal

start: getting a repository under management

Getting started: create the PAT, add the workflow, run your first check, and read the drift output.
Migrating from the Probot Settings app: the step-by-step move, including the parts that changed on purpose and an org-scale shadow run.
Examples: a settings.yml cookbook, from a minimal file to a full-featured one, including what null means where it is meaningful.
Command line: the github-settings-as-code and gsac commands in the npm package, one per action mode plus validate and permissions, their flags, outputs, and exit codes.

reference: the normative model

Sections: every section with its endpoints, PAT permission, undeclared default, and notes.
Coverage: every supported area with one link per call it makes, the facts behind each, the repo-scoped gaps, and what has no public API or is out of scope.
Inputs and outputs: every with: input with its default, and the result, skipped-sections, and repos-result outputs.
Semantics: stateless, declared-keys-only, convergent applies, softenable errors, retries, and the preflight barrier.
Architecture: how the action works in diagrams, from one settings file's journey to the module map, each pinned to the code.
Token permissions: which grant each section needs, how a denial surfaces, and the on-missing-permission / required-sections policy.
The undeclared policy: the _undeclared knob on the list sections, per-section defaults, the milestone-deletion caveat, and how the policy layers in mode: render.
Forward compatibility: where payloads pass through verbatim and which sections are deliberately closed.
Secrets and vaults: the $NAME references secret fields take, wiring them from GitHub Secrets or a vault action, and what check mode can and cannot verify.
Library: the npm package @vivswan/github-settings-as-code, how it is built, the API by group with one example each, and how its version tracks the action's.

operate: day-to-day operation

Check mode: drift detection on a schedule, exit codes, and what a "cannot verify" note is telling you.
Snapshot mode: mode: snapshot writes the live settings as a settings file, the $NAME placeholders secrets become, the round trip and its exceptions, and the per-repo directory form.
Layering settings files: mode: render folds an ordered list of files into one document, the rules of the fold, the _layering directive, and the two-step workflow.
Multi-repo mode: manage a fleet from one admin repository with per-repo files, discovery, and a defaults-file fallback for repositories without a file.
Private repositories: the redaction that keeps private targets out of public logs, and the private-report channels.
Troubleshooting: permission denials, ambiguous 403s, rate limits, debug logging, and a missing or stale bundle.

playbooks: complete workflows to adapt

The playbooks compose the pieces above into end-to-end setups: ring rollouts, change previews, trust tiers between tokens, audit evidence, incident freeze, and decommissioning.

upgrading: one guide per major

Upgrading explains how the moving tags work and holds one page per major: v1 to v2 and v2 to v3, each break as a row with its before, after, and the error the old form now produces.

Where the facts live

Generated regions carry the load-bearing facts. Each is rendered from its declarations or generator data by bun run build:docs, bun run build:action-docs, and bun run build:inputs-table, and build:check fails when a committed page drifts:

the Sections table and the result values on the inputs page;
the Inputs table, which action-docs renders from action.yml;
the Coverage tables and notes, the per-section detail behind the Sections table;
the defaults table and count in undeclared policy;
the grant sentence and gated-read bullets in permissions and check mode;
the module map in architecture, rendered from architecture.yml, which bun run lint:arch keeps equal to the import graph.

Contract tests pin the remaining authored claims in forward compatibility, private repositories, and troubleshooting: the commands and enumerations that must not drift. The rest is walkthrough prose. When a walkthrough disagrees with a generated or pinned claim, the claim wins, so guides link to the claims rather than duplicating their exact wording.

The settings examples in these pages are validated in CI against the real schema (test/docs/guides.test.ts): every fenced block tagged yaml settings must be a valid settings document, every block tagged yaml layer must validate as one layer of a merge (nulls stripped first, as the render step does), and a settings-shaped block without a tag fails the build. Every mermaid diagram must name real files and exported symbols and link the test that demonstrates it (test/docs/diagrams.test.ts). If you edit a guide, tag your example blocks.

Guides ​

Pick by goal ​

start: getting a repository under management ​

reference: the normative model ​

operate: day-to-day operation ​

playbooks: complete workflows to adapt ​

upgrading: one guide per major ​

Where the facts live ​