gh-repo-settings
Guide
Guide
English

Commands

init - Initialize Configuration

Create a configuration file interactively.

# Create .github/repo-settings.yaml interactively
gh repo-settings init

# Specify output path
gh repo-settings init -o config.yaml

# Overwrite existing file
gh repo-settings init -f

export - Export Repository Settings

Export current GitHub repository settings to YAML format.

# Export to stdout
gh repo-settings export

# Export to single file
gh repo-settings export -s .github/repo-settings.yaml

# Export to directory (multiple files)
gh repo-settings export -d .github/repo-settings/

# Include secret names
gh repo-settings export -s settings.yaml --include-secrets

# Export from specific repository
gh repo-settings export -r owner/repo -s settings.yaml

plan - Preview Changes

Validate configuration and show planned changes without applying them.

# Preview all changes (uses default config path)
gh repo-settings plan

# Specify config file
gh repo-settings plan -c custom-config.yaml

# Specify config directory
gh repo-settings plan -d .github/repo-settings/

# Show current GitHub settings (useful for debugging)
gh repo-settings plan --show-current

# Check secrets
gh repo-settings plan --secrets

# Check environment variables
gh repo-settings plan --env

# Show variables/secrets to delete (not in config)
gh repo-settings plan --env --secrets --sync

Status Check Validation

When running plan, the tool automatically validates that status_checks names in your branch protection rules match the job names defined in your .github/workflows/ files:

⚠ status check lint not found in workflows ⚠ status check test not found in workflows Available checks: build, golangci-lint, Run tests

apply - Apply Changes

Apply YAML configuration to the GitHub repository.

# Apply changes (uses default config path)
gh repo-settings apply

# Auto-approve without confirmation
gh repo-settings apply -y

# Specify config file
gh repo-settings apply -c custom-config.yaml

# Apply from directory
gh repo-settings apply -d .github/repo-settings/

# Apply variables and secrets
gh repo-settings apply --env --secrets

# Sync mode: delete variables/secrets not in config
gh repo-settings apply --env --secrets --sync

Global Options

Option Description
-v, --verbose Show debug output
-q, --quiet Only show errors
-r, --repo <owner/name> Target repository (default: current)
On this page