A fast, declarative CLI tool to manage GitHub organization configuration as code, written in Rust.
- Features
- Why use gh-config-cli?
- Supported Platforms
- Installation
- Usage
- Configuration
- GitHub Actions Integration
- Local Development
- Security Considerations
- Contributing
- License
- Documentation
- Getting Help
- Declarative YAML config for your entire GitHub org: repos, teams, members, permissions, webhooks, branch protections.
- Diff mode: See what would change before applying.
- Dry run: Validate changes without modifying anything.
- Sync from org: Generate a config file from your current GitHub org state.
- GitHub Apps: Validate versioned manifests and register org-owned Apps through GitHub's browser approval flow.
- Cross-platform: Linux, macOS, Windows.
- Fast: Built in Rust.
- Easy CI integration: Automate validation and updates.
- No vendor lock-in: Open source under MIT license.
Managing GitHub orgs manually or with scattered scripts is error-prone. gh-config-cli lets you:
- Version control your org structure.
- Review changes via diffs and pull requests.
- Enforce consistent settings across repos.
- Automate org management in CI/CD.
- Avoid surprises from manual changes.
- Linux (x86_64, ARM64)
- macOS (Intel & Apple Silicon)
- Windows
Using UBI
mkdir -p "$HOME/bin"
curl --silent --location https://raw.githubusercontent.com/houseabsolute/ubi/master/bootstrap/bootstrap-ubi.sh | sh
"$HOME/bin/ubi" --project gitkb/gh-config-cli --exe gh-config --in "$HOME/bin"Download the latest binary for your platform from Releases, make it executable, and put it in your PATH.
cargo install --locked --git https://github.com/gitkb/gh-config-cliRequires Rust stable:
git clone https://github.com/gitkb/gh-config-cli.git
cd gh-config-cli
cargo build --release
./target/release/gh-config --help- Use a GitHub Personal Access Token (PAT) with appropriate permissions (repo admin, org admin).
- Pass via
--tokenflag orGITHUB_TOKENenvironment variable.
- Diff local config with GitHub:
gh-config --token <your-pat> diff config.yaml- Apply config (sync):
gh-config --token <your-pat> sync config.yaml- Dry run (validate):
gh-config --token <your-pat> sync config.yaml --dry-run- Generate config from org:
gh-config --token <your-pat> sync-from-org config.yaml --org gitkb- Register an organization-owned GitHub App:
gh-config app validate --manifest apps/rabbit.json
gh-config app create --org gitkb --manifest apps/rabbit.json \
--credentials-dir "$HOME/rabbit-app-credentials"Open the printed loopback URL in a browser signed into GitHub with permission
to create Apps under the organization. Confirm the organization on GitHub's
creation page. The CLI rejects personal-account fallback, validates the
callback state, exchanges the one-time code and saves credentials.json,
private-key.pem and nonsecret app.json. No PAT is required or sent by these
App commands. The manifest's redirect_url is replaced with the local callback.
Credential output requires Unix, a new directory outside Git and an existing parent. The directory is mode 0700; files are mode 0600 and never overwritten. Move the secret files into your team's secret manager. Do not commit them or upload them as CI artifacts. Keep only the manifest in your org-config repo.
App registration is a browser-approved operation; an owner PAT in Actions does not bypass GitHub's registration page. Install the resulting App separately using the printed installation URL. Registration expires locally after 15 minutes. See GitHub's manifest flow.
- allow_merge_commit: true
+ allow_merge_commit: falseReleases use the package version declared in Cargo.toml. After main's checks
pass, a new version is tagged and built locally in this repository's workflows;
no private reusable workflow is required. Release builds cover Linux x86_64
and arm64, macOS Intel and Apple Silicon, and Windows x86_64. The previous
release remains available for FreeBSD, Windows arm64 and 32-bit platforms.
gh-config uses a declarative YAML schema. Repo settings take the fields of GitHub's repository endpoints in gh-config's API mapping (src/github_api_mapping_generated.rs): endpoints under /repos/{owner}/{repo} that need nothing but the repo's name. A key the mapping sends to the org or a user is refused, so a misplaced key can't change either.
Every command refuses a config with a key it doesn't know before it contacts GitHub, naming the file, where the key is and the keys allowed there:
config.yaml: repos[3].settings (repo old-tool): unknown setting `archive`. Did you mean `archived`? ...
config.yaml: repos[3].settings (repo old-tool): `default_repository_permission` is not a repository setting: it would be sent to PATCH /orgs/{org}, which is not the repo. ...
config.yaml: repos[3].archived: unknown field `archived`, expected one of `name`, `settings`, `visibility`, `use_default_webhook`, `webhook`, `branch_protections`, `required_checks`, `required_checks_bypass`
Example config.yaml:
org: gitkb
repos:
- name: harmony
settings:
allow_merge_commit: false
allow_squash_merge: true
allow_rebase_merge: true
# Any other GitHub repo setting in the API mapping
teams:
- name: core-team
members:
- adminuser
- otheruser
users:
- login: adminuser
role: admin
assignments:
- repo: harmony
team: core-team
permission: pusharchived is a repo setting like any other:
repos:
- name: old-tool
settings:
archived: true # archive it; `archived: false` unarchives itsync-from-orgwritesarchived: truefor repos that are archived on GitHub, and nothing for the others.syncunarchives a repo before changing anything else on it, and archives repos after every other change, because GitHub makes an archived repo read-only.- A repo that is archived on GitHub and has no
archived: falsekeeps its settings and webhook:syncleaves them as they are and logs one line saying so (shown withRUST_LOG=info, like its other per-change lines). Leavingarchivedout never unarchives a repo. - Team access (
assignments) is sent for archived repos too, sosyncapplies whatdiffshows. GitHub's docs say an archived repo's permissions are read-only; if GitHub refuses a change,syncstops with GitHub's message. Unarchive the repo first (archived: false) or change the assignment to match GitHub. diffshows archiving and unarchiving as a change to thearchivedline. A repo archived on GitHub whose config leavesarchivedout shows- archived: truealone: the config doesn't record it yet (sync-from-org would add it), andsyncleaves the repo archived.
The top-level visibility is used only to create a repo: sync never changes an existing repo's visibility from it (diff and sync-from-org still compare and record it). To change an existing repo's visibility, set settings.visibility or settings.private; sync refuses the two when they contradict each other.
sync creates a repo the config lists and GitHub doesn't have, with the config's visibility, then applies its settings, rulesets and team access. A missing repo without visibility is refused rather than guessed. sync --dry-run prints Would create and skips the rest of that repo, since there is nothing to read yet; every check that needs only the config runs for it too, before anything is written.
This also brings back a repo someone deleted on GitHub while the config still lists it: until the config drops it, the next sync recreates it empty, and the drift check then sees nothing to report. Remove a repo from config.yaml in the same change that deletes it. GitHub restores a deleted repo only while no other repo has its name, so restoring one that was recreated means deleting the empty one first.
repos:
- name: service
visibility: private
settings:
allow_auto_merge: true # PRs may merge themselves once their required checks pass
access_level: organization # other private repos in the org may call this repo's reusable workflows- Like
archived,sync-from-orgwritesallow_auto_merge: trueand anaccess_levelother thannoneonly when GitHub has them;difftreatsallow_auto_merge: falseandaccess_level: nonein a config as GitHub's defaults, not differences. access_level(GitHub's/actions/permissions/access:none,userororganization) exists only for private repos. A level other thannoneon a repo that ends up public is refused. A repo ends up public by itssettings.visibilityorsettings.private, whichsyncwrites; without them it stays as it is on GitHub, or, whensynccreates it, as its top-levelvisibility. When the settings alone decide, the refusal comes before anything is written, dry runs included; otherwise it comes whensyncreaches that repo, before its first write. Going private,syncwrites the visibility first and the access level after it.syncreads it only for repos whose config names it, and writes it only when it differs.sync-from-organddiffread it for every private repo: one extra request each. If that read fails, the repo keeps the file's value anddiffnames it and exits 1.
repos:
- name: service
required_checks: [Format, Unit Tests, "Clippy & Docs"]
required_checks_bypass: # optional: who may merge past the checks, and how
- team: core-team
mode: pull_request # only by merging a PR; `always` also allows direct pushessynckeeps them in the repo's own ruleset namedRequire CI: active, on the default branch (~DEFAULT_BRANCH), not strict (a PR needn't be up to date with the branch), onerequired_status_checksrule. It creates the ruleset if the repo has none by that name and rewrites it when its checks (in any order) or any of those properties differ. An existingRequire CIruleset is adopted by name.- A check the ruleset already pins to an app (
integration_id, e.g. GitHub Actions) keeps that pin whensyncrewrites the ruleset; a new check gets none. The pin isn't part of the config or the drift check. allow_auto_mergeis written after the repo'sRequire CIruleset, so if the ruleset write fails, auto-merge isn't left on without the checks it waits for.- A name listed twice is refused when the config is loaded. A
Require CIruleset that requires one check twice (from different apps) is refused like one with another rule: a config can't say which pin to keep. - gh-config owns every rule in
Require CI: if it holds any other rule,syncstops with an error naming the repo and the rule instead of dropping it. Keep other rules in other rulesets. required_checks_bypassis the ruleset's whole bypass list:syncmakes it exactly these teams (by slug), so leaving it out removes every bypass, including the org's admins, apps and roles a ruleset can name but a config can't.modeispull_request(merging a PR may skip the checks; a direct push may not) oralways. A team that isn't in the config'steams(when it lists any), a team named twice, an unknown mode, or a bypass list withoutrequired_checksis refused when the config is loaded;synccreates the config'steamsbefore it touches any repo, so a bypass list may name a team the same config adds. A team that neither the org nor the config'steamshas is refused beforesyncwrites anything.sync --dry-runnames the checks an update would stop requiring, who may bypass them after it and who no longer may.- A repo with no
required_checksis left alone:syncdoesn't read or delete its rulesets. To stop requiring checks, delete the ruleset on GitHub and the key. sync-from-orgrecords the checks of each repo'sRequire CIruleset, in the file's order when the file names the same ones;diffcompares them as a set. It costs one rulesets request per repo, plus one whenRequire CIexists. A ruleset that can't be read keeps what the file has, anddiffnames the repo and exits 1. It records the bypass list too, reading team ids as slugs (one teams request in all). GitHub shows a ruleset's bypass list only to a token that can administer the repo; when it doesn't, or the list holds anything other than the org's teams, the file's list is kept anddiffnames the repo and exits 1. A ruleset that requires no checks is recorded without them and without a bypass list (a config can't hold a bypass list alone), andsync-from-orgnever writes a config that wouldn't load: it stops and leaves the file as it is. Properties other than the checks and the bypass list aren't recorded, sodiffshows no change when only those differ;syncstill corrects them.
A repo gets a webhook only if the config says so: its own webhook, or use_default_webhook: true for the org's default_webhook. Being listed connects nothing, and sync never deletes a webhook.
default_webhook:
url: https://example.com/hook
content_type: json
events: [push, pull_request]
repos:
- name: on-the-feed
use_default_webhook: true
- name: not-on-the-feedsync --dry-runprints every webhook it would create or update, by repo, whateverRUST_LOGsays. Each line shows the URL's host, not the whole URL.sync-from-orgrecords what GitHub has. It keeps the file'sdefault_webhookand setsuse_default_webhook: trueonly on repos that have that webhook, so regenerating adds no repo to it. A config holds one webhook per repo, so a repo with several is recorded with itswebhookfrom the file if it has that one, else the default, else its first. If the file has no default, the first webhook found becomes it. If a repo's webhooks can't be read, as with a token that can't read hooks, it stays as the file has it and the command names those repos.diffnever calls webhooks it couldn't read a match: it names those repos and exits 1.- A repo opted in but not yet synced has no webhook on GitHub, so regenerating clears its
use_default_webhook. The same goes for an archived repo, whichsyncskips: runsyncfirst, and don't opt in archived repos. - To take a repo off the default, delete its webhook on GitHub as well as the key: while the webhook exists,
diffreports it andsync-from-orgopts the repo back in. - Changing
default_webhook.urladds a second webhook on each opted-in repo, and the old one keeps delivering until you delete it. - A repo with both
use_default_webhook: trueand its ownwebhook, or with nodefault_webhookto use, is refused.
Upgrading from 1.3.0: a config with default_webhook and no use_default_webhook keeps working but connects nothing new. Add the key to each repo that should have the default, or run sync-from-org to mark the repos that already have it. That marks every repo holding the webhook, so delete any that shouldn't have it first.
You can provide a defaults.config.yaml file to specify org-wide or policy defaults. All fields are optional. The main config takes precedence over defaults.
Example defaults.config.yaml:
repos:
- settings:
allow_merge_commit: true
default_webhook:
url: https://discord.com/api/webhooks/...
content_type: json
events: [push, pull_request]
default_branch_protections:
- pattern: main
enforce_admins: true
allow_deletions: false
allow_force_pushes: falseMerging rules:
- If a setting exists in both main config and defaults, main config wins.
- If a setting exists only in defaults, it is used unless overridden.
Supports:
- All GitHub API-manageable settings (see GitHub REST API docs)
- An org-wide default webhook for the repos that opt in
- Repo settings (merge options, visibility, webhooks, etc.)
- Teams and members
- User roles
- Team-repo permissions
- Branch protection rules
Automate validation and updates.
permissions:
contents: write
pull-requests: write
jobs:
validate-config:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install UBI
run: |
mkdir -p "$HOME/bin"
curl --silent --location https://raw.githubusercontent.com/houseabsolute/ubi/master/bootstrap/bootstrap-ubi.sh | sh
- name: Install gh-config
run: |
"$HOME/bin/ubi" --project gitkb/gh-config-cli --exe gh-config --in "$HOME/bin"
- name: Validate config
env:
GITHUB_TOKEN: ${{ secrets.GH_PAT }}
run: |
$HOME/bin/gh-config sync config.yaml --dry-run
apply-config:
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
runs-on: ubuntu-latest
needs: validate-config
steps:
- uses: actions/checkout@v4
- name: Install UBI
run: |
mkdir -p "$HOME/bin"
curl --silent --location https://raw.githubusercontent.com/houseabsolute/ubi/master/bootstrap/bootstrap-ubi.sh | sh
- name: Install gh-config
run: |
"$HOME/bin/ubi" --project gitkb/gh-config-cli --exe gh-config --in "$HOME/bin"
- name: Apply config
env:
GITHUB_TOKEN: ${{ secrets.GH_PAT }}
run: |
$HOME/bin/gh-config sync config.yaml- Requires Rust stable (
rustup.rs) - Clone repo, then:
cargo build --release
./target/release/gh-config --help- Use
maketargets for common tasks:
make build
make diff CONFIG_FILE=config.yaml
make sync CONFIG_FILE=config.yaml
make sync-from-github CONFIG_FILE=config.yaml GITHUB_ORG=gitkb- Use fine-grained PATs with least privilege.
- Store tokens in environment variables or GitHub Secrets.
- Never commit secrets to version control.
- Review diffs before applying changes.
- Issues and PRs welcome!
- Please file bugs, suggest features, or contribute code.
- See CONTRIBUTING.md for guidelines.
- Please read and follow our Code of Conduct.
MIT License. See LICENSE for details.
- Creating a GitHub Personal Access Token (PAT)
- Usage Guide
- GitHub Actions CI Examples
- Development Guide
- Architecture Overview
- FAQ
- Changelog
More detailed guides and examples can be found in the docs/ directory.