Governor (gh-governor
) π΅π»ββοΈ
A GitHub (gh
) CLI extension to help audit and enforce governance requirements on repositories by defining and invoking policy-based enforcers.
π Features
- π§ | Interactive search for repos based on given
Enforcers
(CODEOWNERS, branch-protection, etc.)
- π | Generate audit reports of governance status across one, many, or all repositories in an organization or account
- βοΈ | Remediate and act on audit results with custom workflows, create issues, open PRs, etc.
- π | Automate reporting and view details about a repository with a detailed governance audit analysis
- π | Configure custom
Enforcers
allowing for fine-grained governance policy management
π¦ Installation
-
Install the gh
CLI - see the installation
Installation requires a minimum version (2.0.0) of the the GitHub CLI that supports extensions.
-
Install this extension:
gh extension install kfrz/gh-governor
-
Ensure the gh
CLI is authenticated:
gh auth login
Manual Installation
-
Clone the repo:
# git
git clone https://github.com/kfrz/gh-governor
# GitHub CLI
gh repo clone kfrz/gh-governor
-
cd
into the repo directory:
cd gh-governor
-
Install the extension:
gh extension install .
β‘οΈ Usage
Run gh governor --help
for more info:
Usage:
gh governor [flags]
Flags:
-c, --config string use this configuration file (default is $GH_GOVERNOR_CONFIG, or $XDG_CONFIG_HOME/gh-governor/config.yml)
--debug passing this flag will allow writing debug output to debug.log
-h, --help help for gh-governor
βοΈ Configuration
All configuration is provided within a config.yml
file under the extension's directory (either $XDG_CONFIG_HOME/gh-governor
or ~/.config/gh-governor/
or your OS config dir) or $GH_GOVERNOR_CONFIG
.
An example config.yml
file contains:
---
# General configuration for gh-governor
governor:
debug: false
dry_run: false
enforce_all: true
sign_commits: true
verbose: false
# Enforcer configuration. Can be used to enable/disable enforcers, and configure their arguments.
# For more information on enforcers, see https://governor.github.io/docs/enforcers
enforcers:
- name: "CodeownersEnforcer"
enabled: true
arguments:
codeowner_is_team: true
ownership_rules:
- team: "@team"
patterns:
- "path/to/file"
- "path/to/other/file"
- team: "@my-other-team"
patterns:
- "path/to/file"
- "path/to/other/file"
- name: "DefaultBranchNameEnforcer"
enabled: true
arguments:
default_branch_name: "main"
You can run gh governor --config <path-to-file>
to run gh-governor
against another config file.
π Authentication
Typically, gh-governor
uses the same authentication as the gh
CLI.
You can authenticate with gh auth login
or gh auth login --with-token
to use a Personal Access Token (PAT).
CI/CD Authentication
If you are using gh-governor
in a CI/CD environment, you can use the --with-token
flag to authenticate with a PAT.
Scope & Permissions
- The PAT must have the
repo
scope.
- The PAT must have the
read:org
scope if you are using the --org
flag.
π Configuring Enforcers
For repositories, the available default Enforcers are:
CodeownersEnforcer
Argument |
Description |
CodeownerIsTeam |
Boolean, whether or not the CODEOWNER is required to be a team or not. (default true) |
DefaultBranchNameEnforcer
Argument |
Description |
DefaultBranchName |
The enforced name of the default branch (e.g. main ) |
Contributing
gh-governor
is an open source project and contributions are welcome!
Check out the CONTRIBUTING guide to get started.
License & Authors