GHRC

GHRC is a tool for managing GitHub Repository Configurations in a declarative way.

Repository configuration includes

• Labels
• Protected Branches
• Merging Strategies
• Visibility(private or public)
• Topics
• Repository Metadata (Description, Homepage, etc.)

Installation

$ go get github.com/shotat/ghrc

Environment Variables

• GHRC_GITHUB_TOKEN (Required)
  • Your GitHub API Token
  • repo scope is required
• GHRC_GITHUB_API (Optional)
  • GitHub API BaseURL
    • Default: https://api.github.com/
    • Enterprise: https://<domain>/api/v3/

Usage

Import an existing repository state

# ghrc import <repository full name>
$ ghrc import shotat/ghrc > .ghrc.yaml

Check expected changes without changing the actual state

$ ghrc plan

This command reads .ghrc.yaml file implicitly. You can specify a config file explicitly with -f.

$ ghrc plan -f .ghrc.yaml

If --name option is specified, metadata.name is overridden.

$ ghrc plan --name shotat/rbdash

Example

$ ghrc plan

~ Repo: shotat/ghrc
{*state.Repo}.Description:
	-: "GHRC is a tool for managing GitHub Repository Configurations in a declarative way."
	+: "GHRC is an awesome tool for managing GitHub Repository Configurations in a declarative way."
{*state.Repo}.AllowRebaseMerge:
	-: false
	+: true
Sort({*state.Repo}.Topics)[1->?]:
	-: "git"
	+: <non-existent>

+ Label: awesome
{*state.Label}:
	-: (*state.Label)(nil)
	+: &state.Label{Name: "awesome", Description: "Awesome issue", Color: "d73a4b"}

~ Label: bug
{*state.Label}.Color:
	-: "d73a4a"
	+: "d73a4b"

~ Label: documentation

~ Label: review

- Label: question
{*state.Label}:
	-: &state.Label{Name: "question", Description: "Further information is requested", Color: "d876e3"}
	+: (*state.Label)(nil)

~ Protection: master
{*state.Protection}.RequiredStatusChecks.Strict:
	-: false
	+: true
{*state.Protection}.RequiredStatusChecks.Contexts[0->?]:
	-: "ci/dockercloud"
	+: <non-existent>
{*state.Protection}.RequiredPullRequestReviews.RequiredApprovingReviewCount:
	-: 1
	+: 2

Apply specs to the actual state

$ ghrc apply

This command reads .ghrc.yaml file implicitly. You can specify a config file explicitly with -f.

$ ghrc apply -f .ghrc.yaml

If --name option is specified, metadata.name is overridden.

$ ghrc apply --name shotat/rbdash

Schema

Root

Metadata Object

Spec Object

Repo Object

Check details in GitHub API docs: Repositories

NOTE: Each field is not managed by GHRC when omitted or specified to null

Label Object

Check details in GitHub API docs: Labels

Protection Object

Check details in GitHub API docs: Branches

RequiredStatusChecks Object

RequiredPullRequestReviews Object

Example

metadata:
  name: shotat/ghrc
spec:
  repo:
    description: GHRC is a tool for managing GitHub Repository Configurations in a declarative way.
    homepage: "https://github.com/shotat/ghrc"
    private: false
    allowMergeCommit: false
    allowSquashMerge: true
    allowRebaseMerge: false
    topics:
    - cli
    - git
    - github
    - go
  labels:
  - name: bug
    description: Something isn't working
    color: d73a4a
  - name: documentation
    description: Improvements or additions to documentation
    color: 0075ca
  - name: question
    description: Further information is requested
    color: d876e3
  - name: review
    description: "ready for review"
    color: f0f0f0
  protections:
  - branch: master
    requiredStatusChecks:
      strict: false
      contexts:
      - ci/dockercloud
    enforceAdmins: false
    requiredPullRequestReviews:
      dismissStaleReviews: false
      requireCodeOwnerReviews: false
      requiredApprovingReviewCount: 1