Getting Started

Prerequisites

• gh CLI installed and authenticated (gh auth login)
• Repositories you want to manage must be accessible with your current gh token

Installation

gh extension

gh extension install babarot/gh-infra

Recommended. Installs as a gh subcommand — run gh infra plan, gh infra apply, etc. Authentication is shared with gh auth, so no additional token setup is needed.

Homebrew

brew install babarot/tap/gh-infra

Installs as a standalone binary. Run as gh-infra plan directly. Note that gh CLI is still required as gh-infra uses it internally for GitHub API calls.

Go

go install github.com/babarot/gh-infra/cmd/gh-infra@latest

Build from source. Installs as a standalone binary, same as Homebrew.

Verify the installation:

gh infra --help

Quick Start

1. Import an existing repository

   Start by exporting a repository’s current settings to YAML:

   gh infra import babarot/my-project > repos/my-project.yaml

   This generates a complete YAML manifest reflecting the repository’s current state on GitHub.

2. Edit the YAML

   Open the file and change what you want. For example, enable discussions, disable wiki, and add topics:

   apiVersion: gh-infra/v1
   kind: Repository
   metadata:
     name: my-project
     owner: babarot
   
   spec:
     description: "My awesome project"
     visibility: public
     topics:
       - go
       - cli
     features:
       issues: true
       projects: false
       wiki: false
       discussions: true

3. Preview changes

   Run plan to see what would change without making any modifications:

   gh infra plan ./repos/

     ~ babarot/my-project                                      2 to update
         ~ features
             ~ wiki         true  → false
             ~ discussions  false → true
         ~ topics  [] → [go, cli]
   
   Plan: + 0 to create   ~ 2 to update   - 0 to destroy
         in 1 repository

4. Apply

   When you’re happy with the plan, apply:

   gh infra apply ./repos/

   gh-infra will show the plan again and ask for confirmation before making changes.

What’s Next?

gh-infra supports four resource kinds:

Kind	What it does
Repository	Manage a single repo’s settings
RepositorySet	Manage many repos with shared defaults
File	Manage files in a single repo
FileSet	Distribute files (LICENSE, CODEOWNERS, workflows) across repos

See the Resources for the full specification, or check out the Guides for different usage patterns.

To run gh-infra in GitHub Actions (plan each pull request with a comment, apply on merge, detect drift on a schedule), see CI/CD Integration.