Skip to content

About

No description, website, or topics provided.

Resources

Code of conduct

Contributing

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

gh-config-cli

CI License: MIT Releases

A fast, declarative CLI tool to manage GitHub organization configuration as code, written in Rust.


Table of Contents


Features

  • 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.

Why use gh-config-cli?

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.

Supported Platforms

  • Linux (x86_64, ARM64)
  • macOS (Intel & Apple Silicon)
  • Windows

Installation

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"

From GitHub Releases

Download the latest binary for your platform from Releases, make it executable, and put it in your PATH.

With Cargo

cargo install --locked --git https://github.com/gitkb/gh-config-cli

From Source

Requires Rust stable:

git clone https://github.com/gitkb/gh-config-cli.git
cd gh-config-cli
cargo build --release
./target/release/gh-config --help

Usage

Authentication

  • Use a GitHub Personal Access Token (PAT) with appropriate permissions (repo admin, org admin).
  • Pass via --token flag or GITHUB_TOKEN environment variable.

Commands

  • 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.

Example diff output

- allow_merge_commit: true
+ allow_merge_commit: false

Releases

Releases 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.

Configuration

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: push

Archiving repos

archived is a repo setting like any other:

repos:
  - name: old-tool
    settings:
      archived: true    # archive it; `archived: false` unarchives it
  • sync-from-org writes archived: true for repos that are archived on GitHub, and nothing for the others.
  • sync unarchives 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: false keeps its settings and webhook: sync leaves them as they are and logs one line saying so (shown with RUST_LOG=info, like its other per-change lines). Leaving archived out never unarchives a repo.
  • Team access (assignments) is sent for archived repos too, so sync applies what diff shows. GitHub's docs say an archived repo's permissions are read-only; if GitHub refuses a change, sync stops with GitHub's message. Unarchive the repo first (archived: false) or change the assignment to match GitHub.
  • diff shows archiving and unarchiving as a change to the archived line. A repo archived on GitHub whose config leaves archived out shows - archived: true alone: the config doesn't record it yet (sync-from-org would add it), and sync leaves the repo archived.

Creating repos

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.

Auto-merge and Actions access

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-org writes allow_auto_merge: true and an access_level other than none only when GitHub has them; diff treats allow_auto_merge: false and access_level: none in a config as GitHub's defaults, not differences.
  • access_level (GitHub's /actions/permissions/access: none, user or organization) exists only for private repos. A level other than none on a repo that ends up public is refused. A repo ends up public by its settings.visibility or settings.private, which sync writes; without them it stays as it is on GitHub, or, when sync creates it, as its top-level visibility. When the settings alone decide, the refusal comes before anything is written, dry runs included; otherwise it comes when sync reaches that repo, before its first write. Going private, sync writes the visibility first and the access level after it. sync reads it only for repos whose config names it, and writes it only when it differs. sync-from-org and diff read it for every private repo: one extra request each. If that read fails, the repo keeps the file's value and diff names it and exits 1.

Required checks

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 pushes
  • sync keeps them in the repo's own ruleset named Require CI: active, on the default branch (~DEFAULT_BRANCH), not strict (a PR needn't be up to date with the branch), one required_status_checks rule. 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 existing Require CI ruleset is adopted by name.
  • A check the ruleset already pins to an app (integration_id, e.g. GitHub Actions) keeps that pin when sync rewrites the ruleset; a new check gets none. The pin isn't part of the config or the drift check.
  • allow_auto_merge is written after the repo's Require CI ruleset, 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 CI ruleset 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, sync stops with an error naming the repo and the rule instead of dropping it. Keep other rules in other rulesets.
  • required_checks_bypass is the ruleset's whole bypass list: sync makes 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. mode is pull_request (merging a PR may skip the checks; a direct push may not) or always. A team that isn't in the config's teams (when it lists any), a team named twice, an unknown mode, or a bypass list without required_checks is refused when the config is loaded; sync creates the config's teams before 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's teams has is refused before sync writes anything.
  • sync --dry-run names the checks an update would stop requiring, who may bypass them after it and who no longer may.
  • A repo with no required_checks is left alone: sync doesn't read or delete its rulesets. To stop requiring checks, delete the ruleset on GitHub and the key.
  • sync-from-org records the checks of each repo's Require CI ruleset, in the file's order when the file names the same ones; diff compares them as a set. It costs one rulesets request per repo, plus one when Require CI exists. A ruleset that can't be read keeps what the file has, and diff names 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 and diff names 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), and sync-from-org never 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, so diff shows no change when only those differ; sync still corrects them.

Webhooks

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-feed
  • sync --dry-run prints every webhook it would create or update, by repo, whatever RUST_LOG says. Each line shows the URL's host, not the whole URL.
  • sync-from-org records what GitHub has. It keeps the file's default_webhook and sets use_default_webhook: true only 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 its webhook from 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.
  • diff never 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, which sync skips: run sync first, 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, diff reports it and sync-from-org opts the repo back in.
  • Changing default_webhook.url adds 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: true and its own webhook, or with no default_webhook to 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.

Defaults and Merging

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: false

Merging 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

GitHub Actions Integration

Automate validation and updates.

Validate on PRs, apply on main branch push

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

Local Development

  • Requires Rust stable (rustup.rs)
  • Clone repo, then:
cargo build --release
./target/release/gh-config --help
  • Use make targets 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

Security Considerations

  • 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.

Contributing

  • 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.

License

MIT License. See LICENSE for details.

Documentation

More detailed guides and examples can be found in the docs/ directory.

Getting Help

  • See the FAQ for common questions.
  • Open an issue on GitHub.

About

No description, website, or topics provided.

Resources

Code of conduct

Contributing

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages