gh-repo-settings
Guide
Guide
English

Configuration Reference

repo - Repository Settings

Field Type Description
description string Repository description
homepage string Homepage URL
visibility public | private | internal Repository visibility
allow_merge_commit boolean Allow merge commits
allow_rebase_merge boolean Allow rebase merging
allow_squash_merge boolean Allow squash merging
delete_branch_on_merge boolean Auto-delete head branches
allow_update_branch boolean Allow updating PR branches

topics - Repository Topics

Array of topic strings:

topics:
  - javascript
  - nodejs
  - cli

labels - Issue Labels

Field Type Description
replace_default boolean Delete labels not in config
items array List of label definitions
items[].name string Label name
items[].color string Hex color (without #)
items[].description string Label description

branch_protection - Branch Protection Rules

branch_protection:
  <branch_name>:
    # Pull request reviews
    required_reviews: 1          # Number of required approvals
    dismiss_stale_reviews: true  # Dismiss approvals on new commits
    require_code_owner: false    # Require CODEOWNERS review

    # Status checks
    require_status_checks: true  # Require status checks
    status_checks:               # Required status check names
      - ci/test
    strict_status_checks: false  # Require up-to-date branches

    # Deployments
    required_deployments:        # Required deployment environments
      - production

    # Commit requirements
    require_signed_commits: false # Require signed commits
    require_linear_history: false # Prevent merge commits

    # Push/merge restrictions
    enforce_admins: false        # Include administrators
    restrict_creations: false    # Restrict branch creation
    restrict_pushes: false       # Restrict who can push
    allow_force_pushes: false    # Allow force pushes
    allow_deletions: false       # Allow branch deletion

env - Environment Variables and Secrets

Manage repository variables and secrets:

env:
  # Variables with default values (can be overridden by .env file)
  variables:
    NODE_ENV: production
    API_URL: https://api.example.com
  # Secret names (values come from .env file or interactive prompt)
  secrets:
    - API_TOKEN
    - DEPLOY_KEY
Field Type Description
variables map Key-value pairs for repository variables
secrets array List of secret names to manage

Using .env File

Create a .github/.env file (gitignored) to store actual values:

# .github/.env
NODE_ENV=staging
API_URL=https://staging-api.example.com
API_TOKEN=your-secret-token
DEPLOY_KEY=your-deploy-key

Priority: .env file values override YAML defaults for variables.

Commands

# Preview variable/secret changes
gh repo-settings plan --env --secrets

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

# Delete variables/secrets not in config (sync mode)
gh repo-settings apply --env --secrets --sync

If a secret value is not found in .env, you'll be prompted to enter it interactively during apply.

actions - GitHub Actions Permissions

actions:
  # Enable/disable GitHub Actions
  enabled: true

  # Which actions can be used: "all", "local_only", "selected"
  allowed_actions: selected

  # When allowed_actions is "selected"
  selected_actions:
    github_owned_allowed: true    # Allow actions from GitHub
    verified_allowed: true        # Allow actions from verified creators
    patterns_allowed:             # Allow specific action patterns
      - "actions/*"
      - "github/codeql-action/*"

  # Default GITHUB_TOKEN permissions: "read" or "write"
  default_workflow_permissions: read

  # Allow GitHub Actions to create/approve pull requests
  can_approve_pull_request_reviews: false
Field Type Description
enabled boolean Enable GitHub Actions for this repository
allowed_actions all | local_only | selected Which actions are allowed
selected_actions.github_owned_allowed boolean Allow actions created by GitHub
selected_actions.verified_allowed boolean Allow actions from verified creators
selected_actions.patterns_allowed array Patterns for allowed actions
default_workflow_permissions read | write Default GITHUB_TOKEN permissions
can_approve_pull_request_reviews boolean Allow Actions to approve PRs

pages - GitHub Pages Configuration

pages:
  # Build type: "workflow" (GitHub Actions) or "legacy" (branch-based)
  build_type: workflow

  # Source configuration (only for legacy build type)
  source:
    branch: main
    path: /docs  # "/" or "/docs"
Field Type Description
build_type workflow | legacy How Pages is built
source.branch string Branch for legacy builds
source.path / | /docs Path within the branch
On this page