Managing GitHub Repository Settings with Probot Settings¶

GitHub repository settings can be managed through the web UI, the REST API, or the gh CLI. Default branch, merge strategies, issue tracking, vulnerability alerts, labels, branch protection rules: regardless of how you change them, the result is the same: no audit trail tied to your repository, no peer review process, and no straightforward way to reproduce the configuration in another repository without repeating the same steps manually.

The Probot Settings app solves that problem by treating repository configuration as code. You commit a .github/settings.yml file to your repository, and the app syncs its contents to GitHub's API every time the file changes. The settings are versioned, reviewable, and repeatable.

This post covers how the app works, how to install it, what it can configure, and how to structure a settings.yml file that covers the settings I apply to every project.

How It Works¶

The Probot Settings app is a GitHub App built on the Probot framework. Once installed on a repository or organization, it listens for push events on the default branch. When a push touches .github/settings.yml, the app reads the file and calls the GitHub API to apply the configuration it describes.

The sync is one-directional: the file is the source of truth. If you change a setting in the web UI after committing the file, the next push that modifies settings.yml will overwrite your manual change. If you want to make a permanent change to a setting managed by the file, you change the file.

This model makes repository configuration reviewable. A pull request that changes settings.yml goes through the same review process as any other change. The diff shows exactly what is changing. An approver can reason about it before it is merged. The history of the file is the history of the repository's configuration.

Installing the App¶

The Probot Settings app is available as a free, open-source GitHub App. You can install it directly from its GitHub Marketplace listing or self-host the application if your organization requires it.

To install from GitHub Marketplace:

1. Navigate to the app's installation page.
2. Click Install.
3. Choose the account (personal or organization) where you want to install it.
4. Select All repositories or choose specific repositories.
5. Click Install.

After installation, the app has permission to read repository metadata and write repository settings, labels, collaborators, teams, and branch protection rules.

To enable the app for a repository, commit a .github/settings.yml file to the default branch. The next push that touches that file will trigger a sync. If no push occurs after the initial commit, you can trigger a manual sync by pushing any change to the file.

The settings.yml File¶

The file lives at .github/settings.yml in the repository root and is structured as a YAML document with top-level keys that correspond to the categories of settings the app can manage.

Repository¶

The repository key configures top-level repository properties:

repository:
  name: my-repo
  description: A short description of the repository.
  homepage: https://example.github.io/example-repo
  topics: topic-one, topic-two
  private: false
  archived: false
  has_issues: true
  has_projects: false
  has_wiki: false
  has_downloads: false
  default_branch: main
  allow_squash_merge: true
  allow_merge_commit: false
  allow_rebase_merge: false
  delete_branch_on_merge: true
  enable_automated_security_fixes: true
  enable_vulnerability_alerts: true

The topics field accepts a comma-separated string of topic names. GitHub normalizes topics to lowercase and replaces spaces with hyphens. The name field renames the repository, so be careful: if the repository is renamed, any URLs or clones using the old name will need to be updated.

Labels¶

The labels key defines the complete set of labels for the repository. Each label entry requires a name and color. The description field is optional but recommended.

labels:
  - name: bug
    color: '#d73a4a'
    description: Something is not working.
  - name: enhancement
    color: '#0075ca'
    description: New feature or improvement.
  - name: documentation
    color: '#0075ca'
    description: Improvements or additions to documentation.
  - name: chore
    color: '#84D396'
    description: Build, dependencies, or workflow maintenance.

Color values must be hex strings with a leading #, quoted to prevent YAML from interpreting the # as a comment character.

Collaborators¶

The collaborators key grants or updates individual user access to the repository. Each entry requires a username and a permission level:

collaborators:
  - username: peter-gibbons
    permission: push
  - username: michael-bolton
    permission: pull

Valid permission values are pull, triage, push, maintain, and admin.

Teams¶

The teams key grants repository access to GitHub teams. Each entry requires the team's name (as it appears in the organization) and a permission level:

teams:
  - name: engineering
    permission: push
  - name: security
    permission: maintain

Team names are case-insensitive and use the team's slug (hyphens, no spaces).

Branches¶

The branches key configures branch protection rules. Each entry targets a branch by name and accepts a protection block:

branches:
  - name: main
    protection:
      required_pull_request_reviews:
        required_approving_review_count: 1
        dismiss_stale_reviews: true
        require_code_owner_reviews: true
      required_status_checks:
        strict: true
        contexts: []
      enforce_admins: true
      restrictions: null

The restrictions field controls which users, teams, and apps can push directly to the branch. Setting it to null removes restrictions. Setting it to an object with users, teams, and apps arrays restricts direct pushes to those principals.

A Complete Example¶

Here is the full settings.yml I use as a starting point for my open-source repositories. It reflects the settings and labels from my projects and is designed to be a template that can be adapted for any project:

# These settings are synced to GitHub by the Probot Settings app.
# Reference: https://probot.github.io/apps/settings/.

repository:
  name: example-repo
  description: A short description of the repository.
  homepage: https://example.github.io/example-repo
  topics: topic-one, topic-two
  archived: false
  has_issues: true
  has_projects: false
  has_wiki: false
  has_downloads: false
  default_branch: main
  allow_squash_merge: true
  allow_merge_commit: false
  allow_rebase_merge: false
  delete_branch_on_merge: true
  enable_automated_security_fixes: true
  enable_vulnerability_alerts: true

labels:
  - name: bug
    color: '#d73a4a'
    description: Bug
  - name: chore
    color: '#84D396'
    description: Chore
  - name: dependencies
    color: '#84D396'
    description: Dependencies
  - name: documentation
    color: '#0075ca'
    description: Documentation
  - name: enhancement
    color: '#0075ca'
    description: Enhancement
  - name: github-actions
    color: '#000000'
    description: GitHub Actions
  - name: stale
    color: '#e69138'
    description: Stale

The comment at the top is not required, but it is useful. Anyone browsing the repository who wonders why .github/settings.yml exists and what syncs it will have the answer immediately.

Keeping Configuration Consistent Across Repositories¶

One of the most practical benefits of managing settings as code is that it makes consistency achievable. Once you have a settings.yml that works well for one repository, copying it to a new repository (and updating the name and description fields) gives you the same label set, the same merge strategy, and the same protection rules with no manual work.

For organizations managing many repositories, this is significant. New repositories start with a consistent baseline. Changes to the baseline can be proposed as pull requests, reviewed, and rolled out across repositories in a controlled way. The configuration is auditable: the commit history of settings.yml tells you when a setting changed and who approved the change.

For the full list of supported configuration keys and options, see the Probot Settings documentation and the source repository.