GitHub Settings as Code

Apply declarative repository settings from .github/settings.yml: a loud, stateless replacement for the Probot Settings app that also manages rulesets (branch, tag, and push). Every apply is a visible workflow run that fails with the API's error message; nothing happens silently. The full documentation lives in docs/.

Quick start

1. Create a fine-grained PAT from the pre-filled token form and save it as the ADMIN_TOKEN repository secret. The form starts with every repository permission the action can need (an organization owner adds Members: read by hand); the default GITHUB_TOKEN can never hold them.

2. Add .github/settings.yml (or start from a snapshot of the live settings). The first line gives editor autocomplete and hover docs:

   # yaml-language-server: $schema=https://raw.githubusercontent.com/Vivswan/github-settings-as-code/v2/lib/settings.schema.json # x-release-please-major
   
   repository:
     description: My project
     delete_branch_on_merge: true
   
   labels:
     - name: bug
       color: "d73a4a"

3. Add the workflow and run it from the Actions tab.

   • Keep mode: check for the first run: the drift report lists everything an apply would change or delete, and nothing is written.
   • Read the report. An apply deletes undeclared labels, autolinks, collaborators, Actions variables, and Copilot agents variables.
   • Drop the mode: check line once the report says what you expect. The getting started guide explains the drift output.

   # .github/workflows/settings.yml
   name: Apply Settings
   on:
     push:
       branches: [main]
       paths: [.github/settings.yml]
     workflow_dispatch:
   
   permissions:
     contents: read
   
   jobs:
     apply:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v7
         - uses: Vivswan/github-settings-as-code@v2 # x-release-please-major
           with:
             token: ${{ secrets.ADMIN_TOKEN }}
             mode: check

Versioning

Pin	Points at	Use it for
@v2	The newest release in the major line, so fixes arrive without changing your pin	Production
@vX.Y.Z or a commit SHA	One release, frozen by a ruleset	Byte-stable behavior
@latest	The newest green main commit, packaged; breaking changes arrive here unannounced, ahead of any release	Trying unreleased fixes

• Every pin points at a packaged commit: the child of one main commit, carrying its tree plus the built action. main is source-only and not runnable as an action. The tags up to v2.0.0 point at release commits on main from when main still committed the bundle.
• v2 activates settings keys that were inert on v1: actions.oidc_customization_sub, actions.fork_pr_contributor_approval, actions.fork_pr_workflows_private_repos, and branches[].protection.required_signatures. Audit them before moving a @v1 pin; a stale required_signatures: false would remove a hand-enabled requirement.
• Only the latest release is supported; fixes are not backported (see SECURITY.md). Each major has an upgrade guide.

Library

The same engine is the npm package @vivswan/github-settings-as-code (ESM, Node 22.14 or newer): validate, merge, check, and apply from your own code.

• npm install @vivswan/github-settings-as-code installs the released version; @next installs the newest green main commit as a pre-release. The library reference has the API by group and the versioning rules.
• npx @vivswan/github-settings-as-code@next check --repository o/r --settings-file .github/settings.yml runs the action's check from a terminal. The command line guide has every command.

Docs

Goal	Read
Get one repository under management	Getting started
Copy a settings.yml shape	Examples
Look up what a section manages and deletes	Sections
Look up an input or output	Inputs and outputs
Predict what an apply or a check will do	Semantics
Scope the token	Token permissions
Decide what happens to resources the file does not declare	The undeclared policy
Feed secret values from GitHub Secrets or a vault	Secrets and vaults
Detect drift without changing anything	Check mode
Manage a fleet from one repository	Multi-repo mode
Layer settings files and fold them with mode: merge	Layering settings files
Keep private targets out of public logs	Private repositories
Replace the Probot Settings app	Migrating from Probot
Adapt a complete platform-team workflow	Playbooks
Read a failing run	Troubleshooting
Move a pin to a new major	Upgrading
See how the code is laid out	Architecture
Use the engine from your own code	Library
Run check, apply, or validate from a terminal	Command line

Contributing

The toolchain, the end-to-end harness, and the PR conventions are in CONTRIBUTING.md. Licensed under the Individual and Small Organization License.