ghctl - A GitHub utility
ghctl is both a command-line utility for GitHub, and a GitHub Action that allows you to use the utility in your GitHub Actions workflows.
NOTE: ghctl is in early development and is not quite ready for production use. However, please feel free to try it out and provide feedback!
ghctl CLI
ghctl currently requires a GitHub Personal Access Token (PAT) with at least the following scopes:
read:org
repo
(full control)read:user
You can provide the access token to ghctl in one of the following ways:
- set the
$GITHUB_TOKEN
environment variable - explicitly pass it using the
--access-token
option
Download the latest release binary
You can download the latest release binary (built for Debian Bookworm / Ubuntu 22.04 ) from the Releases page, using the GitHub CLI (gh
) or just curl
:
gh release download -R gitsudo-io/ghctl --pattern ghctl
curl -L https://github.com/gitsudo-io/ghctl/releases/download/v0.1.3/ghctl > ghctl
Then make the file executable (chmod u+x ghctl
) and place it in your $PATH
.
Install using Cargo
To install the ghctl
binary using Cargo, you will need to have Rust 1.66.0 or later installed (rustup).
Local Development / Installation from source
To build and install the ghctl
binary locally, you will need to have Rust 1.66.0 or later installed (rustup).
Clone this repository
Build and install the ghctl
binary
Usage
Retrieve GitHub repository information
ghctl repo get "{owner}/{repo}"
will retrieve information about the specified GitHub repository and output it as JSON.
{
Apply a GitHub repository configuration to a repository
ghctl repo apply "{owner}/{repo}" --config-file {config_file}
will read the specified YAML configuration file and apply it to the specified GitHub repository.
The configuration file should be a YAML file and currently supports the following sections:
Repository team permissions
teams:
:
Where {team-slug}
is the team slug on GitHub, and {permission}
is one of pull
, triage
, push
, maintain
, or admin
.
Example:
teams:
a-team: maintain
When applied to a repository, will grant the a-team
team maintain
permissions on the repository.
Repository collaborators
collaborators:
:
Where {username}
is the GitHub username, and {permission}
is one of pull
, triage
, push
, maintain
, or admin
.
Example:
collaborators:
aisrael: admin
Deployment Environments
environments:
:
reviewers:
- , or
- /{team-slug}
Where {environment}
is the name of the deployment environment, {username}
is the GitHub username, or, if {org}/{team-slug}
is given, then it references a GitHub organization and team.
Example:
environments:
gigalixir:
reviewers:
- aisrael
- gitsudo-io/a-team
When applied to a repository, will create the deployment environment and configure its reviewers accordingly.
Branch Protection Rules
branch_protection_rules:
:
required_status_checks:
contexts:
-
- ...
require_pull_request: true
Where {branch name}
is the name of the branch to protect.
The required_status_checks
is optional, and if given, will require the specified status checks to pass before allowing a branch to be merged. Specify any required status checks by name in the contexts
list.
The require_pull_request
is optional, and if given, will require all commits to be made via a pull request.
Example:
branch_protection_rules:
main:
required_status_checks:
contexts:
- "mix/test"
- "mix/credo"
require_pull_request: true
When applied to a repositody, will protect the main
branch and require a pull request before merging, and require the mix/test
and mix/credo
status checks to pass before allowing a branch to be merged.
Full example
Given a gitsudo.yaml
file containing:
teams:
a-team: maintain
collaborators:
aisrael: admin
environments:
gigalixir:
reviewers:
- aisrael
- gitsudo-io/a-team
branch_protection_rules:
main:
required_status_checks:
contexts:
- "mix/test"
require_pull_request: true
When we execute:
Then we should see output similar to the following:
[2023-06-16T18:33:34Z INFO ] Added team a-team with permission Maintain to repository gitsudo-io/gitsudo
[2023-06-16T18:33:34Z INFO ] Updated collaborator aisrael with permission admin to repository gitsudo-io/gitsudo
[2023-06-16T18:33:34Z INFO ] Created deployment environment gigalixir in repository gitsudo-io/gitsudo
[2023-06-16T18:33:35Z INFO ] Applied branch protection rules to branch main in repository gitsudo-io/gitsudo
[2023-06-16T18:33:35Z INFO ] Applied configuration to gitsudo-io/gitsudo
ghctl GitHub Action
GitHub Action for ghctl
Inputs
Name | Description | Required | Default |
---|---|---|---|
args | Program arguments | Required |
gitsudo-io/ghctl
is also a GitHub Action that allows you to use the ghctl
utility in your GitHub Actions workflows.
For example, given the following workflow:
name: Configure ghctl repository
on:
push:
workflow_dispatch:
jobs:
ghctl-repo-config-apply:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: gitsudo-io/ghctl@main
with:
args: repo config apply gitsudo-io/gitsudo --access-token ${{ secrets.GHCTL_ACCESS_TOKEN }} -F gitsudo.yaml
Then executing the workflow above will perform the equivalent of the earlier command.