Skip to content

README.md

Latest commit

 

History

History
69 lines (57 loc) · 3.47 KB

README.md

File metadata and controls

69 lines (57 loc) · 3.47 KB
Raw

Guides

The documentation for GitHub Settings as Code, in four 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.

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.

reference: the normative model

  • Semantics: stateless, declared-keys-only, convergent applies, softenable errors, retries, and the preflight barrier.
  • 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 with a defaults file.
  • 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.

operate: day-to-day operation

  • Check mode: drift detection on a schedule, exit codes, and what a "cannot verify" note is telling you.
  • Multi-repo mode: manage a fleet from one admin repository with defaults, per-repo files, and discovery.
  • 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.

Where the facts live

Contract tests pin the load-bearing claims to the code: the README's Sections and Inputs tables, COVERAGE.md, and specific claims inside undeclared policy, forward compatibility, private repositories, troubleshooting, and check mode - the defaults, counts, commands, and enumerations that must not drift. The rest is walkthrough prose: when a walkthrough and a pinned claim disagree, the pinned 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, and a settings-shaped block without the tag fails the build. If you edit a guide, tag your example blocks.