Settings

The Probot Settings App syncs repository configuration from version control.

Shared rules cover:

• Default branch, description, topics, homepage
• Issue/PR features (issues, projects, wiki, pages, downloads)
• Merge strategies (allow_squash_merge, allow_merge_commit, allow_rebase_merge)
• delete_branch_on_merge
• Branch protection for master and develop
• Shared label palette

---

Usage

.github/settings.yml

_extends: gh-plumbing:.github/commons-settings.yml

repository:
  name: cookiecutter-gh-project
  description: Template for creating GitHub workflows and projects
  homepage: https://nolte.github.io/cookiecutter-gh-project
  topics: templating, cookiecutter, github

Overrides

Keys in your local .github/settings.yml override the inherited values. Only specify what differs from the shared defaults.

---

Central configuration

.github/commons-settings.yml

---
# These settings are synced to GitHub by https://probot.github.io/apps/settings/
repository:

  # Either `true` to make the repository private, or `false` to make it public.
  private: false

  # Either `true` to enable issues for this repository, `false` to disable them.
  has_issues: true

  # Either `true` to enable projects for this repository, or `false` to disable them.
  # If projects are disabled for the organization, passing `true` will cause an API error.
  has_projects: true

  # Either `true` to enable the wiki for this repository, `false` to disable it.
  has_wiki: true

  has_pages: true

  # Either `true` to enable downloads for this repository, `false` to disable them.
  has_downloads: true

  # Updates the default branch for this repository.
  default_branch: develop

  # Merge strategy: squash-merge only.
  # Forcing a single linear-history strategy keeps `develop` clean and makes
  # release-drafter / Conventional-Commits parsing predictable across all
  # repositories that extend these commons.

  # Either `true` to allow squash-merging pull requests, or `false` to prevent
  # squash-merging.
  allow_squash_merge: true

  # Either `true` to allow merging pull requests with a merge commit, or `false`
  # to prevent merging pull requests with merge commits.
  allow_merge_commit: false

  # Either `true` to allow rebase-merging pull requests, or `false` to prevent
  # rebase-merging.
  allow_rebase_merge: false

  delete_branch_on_merge: true


# <!--td-commons-settings-labels-start-->
# Labels: define labels for Issues and Pull Requests
labels:
  - name: bug
    color: "#CC0000"
    description: An issue with the system.

  - name: enhancement
    color: "#336699"
    description: New functionality.

  - name: chore
    color: "#6e70ef"
    description: Maintenance

  - name: fix
    color: "#d73a4a"
    description: Conventional Commits type `fix` — bug fix.

  - name: feat
    color: "#a2eeef"
    description: Conventional Commits type `feat` — new feature.

  - name: docs
    color: "#0075ca"
    description: Conventional Commits type `docs` — documentation or spec change.

  - name: question
    color: "#3ffc8a"
    description: User question

  - name: documentation
    color: "#caa7e8"
    description: Update documentation.

  - name: cicd
    color: "#fbca04"
    description: ci/cd process functionality.

  - name: project-config
    color: "#ed979d"
    description: Change GitHub project config, keep a extra eye on merge.

  - name: breaking-change
    color: "#fc415d"
    description: Planed braking provider change.

  - name: duplicate
    color: "#cfd3d7"
    description: This issue or pull request already exists.

  - name: dependencies
    color: "#0366d6"
    description: Pull requests that update a dependency file.

  - name: wontfix
    color: "#ffffff"
    description: ""

  - name: automerge
    color: "#19F700"
    description: "Allow automatic Merge."

  - name: spec
    color: "#c5def5"
    description: Touches files under `spec/`.

  - name: skills
    color: "#bfdadc"
    description: Touches files under `skills/`.

  - name: agents
    color: "#c2e0c6"
    description: Touches files under `agents/`.

  - name: claude-code
    color: "#ffd33d"
    description: Touches Claude Code integration (`.claude/`, `.claude-plugin/`, `CLAUDE.md`).

  - name: release
    color: "#5319e7"
    description: Version-alignment PR — excluded from release-drafter changelog.

  - name: github-actions
    color: "#000000"
    description: Touches GitHub Actions workflows under `.github/workflows/`.

  - name: stale
    color: "#cccccc"
    description: Auto-applied by actions/stale to inactive issues and pull requests.

# <!--td-commons-settings-labels-end-->

branches:
  - name: master
    protection:
      required_pull_request_reviews: null
      required_status_checks: null
      enforce_admins: true
      # nolte-portfolio-app is the portfolio GitHub App that the cascade
      # remediation in #330 (Phase 1) wires through every cascade-emitting
      # reusable workflow. Declaring it as a push restriction actor here
      # enables the workflow-driven primary path of
      # spec/project/release-automation/ §Version-bearing file alignment:
      # `reusable-release-cd-refresh-master.yml` fast-forwards master with
      # the App token, and the push event cascades to other workflows.
      #
      # Consumers that own a personal account (not an organisation) cannot
      # honour `restrictions.apps` (GitHub limits this to organisation-owned
      # repositories); the Probot Settings App will skip the field silently
      # for those repositories. Such consumers either operate without
      # restrictions or override this block in their per-repo
      # .github/settings.yml.
      restrictions:
        users: []
        teams: []
        apps:
          - nolte-portfolio-app
  - name: develop
    protection:
      required_pull_request_reviews: null
      required_status_checks:
        # Portfolio-default leaves required contexts empty so this commons
        # config does not impose a gh-plumbing-specific check name on every
        # consumer repo. Consumers MUST declare their own required-check
        # contexts in their per-repo .github/settings.yml. See
        # spec/project/pull-request-workflow §required status checks.
        strict: true
        contexts: []
      enforce_admins: true
      restrictions:
        users: []
        teams: []
        apps:
          - nolte-portfolio-app

---

Versioning, drift, and the _extends contract

_extends @<ref> isn't supported

The Probot Settings App always resolves _extends: from the default branch of the target repository. The parser rejects any @<tag>, @<sha>, ?ref=…, or :vN suffix on the _extends: value outright. It doesn't strip the suffix and continue. See octokit-plugin-config/src/util/extends-to-get-content-params.ts — the regex anchors at the start and excludes @ from the filename token.

Operational consequence. Every consumer lives at the tip of gh-plumbing/develop for its Probot configuration. Whenever a commons-*.yml file changes here, every consumer drifts on its next sync trigger, with no signal back to the consumer. There is no reproducible snapshot: "which commons-settings.yml state did this repository sync last week?" has no answer.

This is a known, accepted trade-off. See issue #337 for the full investigation (parser source, alternatives matrix, decision rationale).

When this trade-off becomes blocking

Three architectural alternatives are available the day drift turns load-bearing:

Approach	Mechanism	Pinning model
github/safe-settings	Central admin repository per org, three-level hierarchy (org/suborg/repo), PR-based dry-run CI	No pinning, but a single source per org eliminates cross-repository _extends resolves
joshjohanning/bulk-github-repo-settings-sync-action	GitHub Action invoked from a central repository on cron/push; inputs are file paths in the calling repository	Action version plus file content at a specific commit, giving a true snapshot
Inline commons-*.yml into each consumer	Inline copy in each consumer's .github/settings.yml with a # generated from gh-plumbing@<tag> header; Renovate Custom Regex Manager bumps the header	Snapshot per consumer commit; full diff in the bump PR

Until then, treat edits to commons-*.yml as a public API change and roll them out as breaking changes.

Why the local .github/settings.yml here carries a propagation comment

gh-plumbing is itself a consumer of its own commons. The Probot App reacts to push events that touch the consumer's .github/settings.yml, not the upstream commons-*.yml. To propagate a commons change, touch this repository's .github/settings.yml as well (a comment bump is enough). Issue #331 tracks this dog-fooding quirk.