Capability Defaults

Codebase governor lets you define capability defaults for repository access and branch protection in a _defaults.yml file.

This public content is an excerpt from Flutter staff GitHub docs. It is published as a reference to show how GitHub is used for inner source at Flutter.

This page explains the format of the Codebase Governor capability _defaults.yml file. The codebase governor capability itself has a commented example of this file. All fields are optional so you can add only what you need.

The defaults file uses YAML syntax, and must have a .yml file extension. If you’re new to YAML and want to learn more, see “Learn YAML in Y minutes”.

owner

The owner key specifies the owner of a capability by their GitHub username. The capability owner team owner-cap-<capability name> has the specified owner as the only member. This team has admin permission to all capability repositories. The team exists so you can reference the owner via this team name in static dependencies like repository CODEOWNERS.

owner: example-github-username

maintainers

The maintainers key specifies the maintainers of a capability as an array of their GitHub usernames. The GitHub maintainers team maintainers-cap-<capability name> has these users as the only members. This team has admin permission to all capability repositories.

maintainers:
  - example-username-1
  - example-username-2

description

The description key contains a description of the capability. Ideally this is a single sentence but can be several short sentences if required. It can’t be more than 1 paragraph (i.e. can’t contain any line breaks).

description: >
  Codebase Governor allows you as a repository owner to manage
  protection and access settings via YAML file config and a
  pull-request workflow.

defaults

The defaults section defines default settings for each repository in the capability:

These defaults can be overridden for individual repositories within the capability in the repository config file.

defaults.branch-protections

The defaults.branch-protections section specifies the default branch protection rules for the capability repositories. Don’t specify defaults if you intend to manage protections manually in the GitHub UI or with your own automation.

Audited Source

Audited Source ensures changes are preserved for audit, but doesn’t require review before releasing changes.

branch-protections:
  - patterns: ["main"]

The default allows-force-pushes and allows-deletions settings ensure that you can’t modify or delete branch history. Since the default values are appropriate, you can simply omit the parameters key.

Reviewed Source

Reviewed Source is a feature branch based workflow where all changes require a codeowner approval before merging to main.

branch-protections:
  - patterns:
      - "main"
    parameters:
      required-reviews-count: 1
      requires-codeowner-reviews: true

The default branch (main or on older repos master):

  • requires a pull request with at least 1 approving review (required-reviews-count: 1).
  • requires a codeowner approval rather than any other user with write permissions (requires-codeowner-reviews: true).

Multiple Team Source

Multiple Team Source is a derivative of GitFlow to provide each team with their own develop branch.

branch-protections:
  - patterns:
      - "main"
      - "support/*"
    parameters:
      required-reviews-count: 2
      requires-codeowner-reviews: true
  - patterns:
      - "*/develop"
      - "*/release/*"
    parameters:
      required-reviews-count: 1
      requires-codeowner-reviews: true
      allow-admin-bypass: true
      allow-stale-reviews: true
      allow-stale-branch-merge: true
      allows-deletions: true

The default and previous version support branches require a pull request with a codeowner review:

  • requires a pull request with at least 2 approving review (required-reviews-count: 2). This encourages cross team review for critical pull requests.
  • requires a codeowner approval rather than any other user with write permissions (requires-codeowner-reviews: true).

Develop and release branches also require branch protection, but settings optimise for development speed:

  • maintainers can push directly to develop and release branches due to enabling allow-admin-bypass. This allows them to perform maintenance directly without waiting for review.
  • Approving reviews remain valid for a pull request after minor feedback fixes (allow-stale-reviews: true). This means the author spends less time chasing re-reviews after minor edits.
  • A branch can merge even if not up-to-date (allow-stale-branch-merge: true). This reduces the time an author spends updating their branch.
  • develop and release branches change over time: so allow deletion via allows-deletions: true.

branch-protections[*].patterns

The branch name pattern to apply the rule to. Due to the GitHub implementation this pattern you must specify this using fnmatch syntax. From GitHub documentation:

You can create a rule for all current and future branches in your repository with the wildcard syntax *. Because GitHub uses the File::FNM_PATHNAME flag for the File.fnmatch syntax, the wildcard doesn’t match directory separators (/). For example, develop/* matches all branches beginning with develop/ and containing a single slash. You can include multiple slashes with develop/**/*, and you can extend the develop string with develop**/**/* to make the rule more inclusive. For more information about syntax options for branch rules, see the fnmatch documentation.

For example, to specify a rule must apply to the default main branch:

branch-protections:
  - patterns: [main]

For example, to match all default, develop, support, and release branches in Multiple Team Source:

branch-protections:
  - patterns:
      - "main"
      - "*/develop"
      - "support/*"
      - "*/release/*"

branch-protections[*].parameters

The protection parameters that to apply to the specified patterns.

branch-protections[*].parameters.required-reviews-count

The number of required reviews before you can merge a pull request. The default value of 0 means any user with write access to the repository can push directly to this branch with no review. A value of 1 means users with write access can’t push directly to this branch, instead they need to raise a pull request and get at least 1 review approval.

required-reviews-count: 1

The GitHub docs provide more information about required reviews.

There are several related parameters:

branch-protections[*].parameters.requires-codeowner-reviews

You can configure “code owners” using the CODEOWNERS file. Usually you specify the capability maintainer team as codeowners.

requires-codeowner-reviews: true

The default value for this parameter is false. If enabled by setting it to true, a pull request requires an approval from the specified code owners before merge. Without this setting enabled, the required-reviews-count approvals come from any user with write access to the repository.

branch-protections[*].parameters.allow-stale-reviews

By default additional changes to a pull request branch dismiss any existing approvals.

Enabling allow-stale-reviews means a pull request approval remains valid even when you make more changes after the review. This is convenient for you as the pull request author as you act on review feedback to implement minor fixes to the pull request – you don’t need to get the pull request re-reviewed after you have pushed your fixes. However, note how it allows you to include additional un-reviewed code to an existing pull request so don’t enable this rule for critical branches where you require strict code review.

allow-stale-reviews: true

branch-protections[*].parameters.allow-admin-bypass

By default the branch protection rule constraints apply to all users, including repository or organisation administrators.

Enabling allow-admin-bypass allows repository and organisation admins to override the restrictions of a branch protection rule. For example this would allow maintainers to push directly to a protected branch that required reviews. This is convenient when repository administrators expect to perform maintenance work on the protected branch as they can bypass the constraints to do so.

allow-admin-bypass: true

branch-protections[*].parameters.requires-status-checks

Required status checks require GitHub status tests to pass before merge. GitHub status checks can be GitHub Action workflows or external checks like a divisional Jenkins or SonarCloud.

requires-status-checks: true

Note that this setting is currently confusing as it doesn’t automatically apply to all status checks. For a required status check this setting needs to apply, AND you need to select the status check in the branch protection GitHub UI.

The GitHub docs provide more information about requiring status checks in pull requests.

branch-protections[*].parameters.allow-stale-branch-merge

When requiring status checks (requires-status-checks) by default the pull request branch must be up-to-date with the base branch. This ensures the status checks have run against the content exactly as it merges.

Enabling allow-stale-branch-merge allows the status checks to remain valid and the pull request to merge even when the pull request branch becomes out of date with the base branch.

allow-stale-branch-merge: true

Advanced Settings

Read more about further branch protection settings in the GitHub docs. A full list:

branch-protections:
  - patterns: [main]
    parameters:
      required-reviews-count: 1
      requires-codeowner-reviews: true
      requires-status-checks: true
      allow-admin-bypass: true
      allow-stale-reviews: true
      allow-stale-branch-merge: true

      # Requires commits to be signed and verified
      requires-commit-signatures: true

      # Requires PR conversations to be marked as resolved
      requires-conversation-resolution: true

      # Prevents merge commits being created on the branch
      requires-linear-history: true

      # By default force pushes and branch deletions are prevented but this
      # can be allowed if desired by switching these settings to 'true':
      allows-force-pushes: false
      allows-deletions: false

      # If push restriction is enabled then only users, teams, or apps
      # that have been given permission can push to the protected branch.
      #
      # It is not possible for codebase governor to manage the users, teams
      # and apps specified so these need to be manually set in the GitHub
      # interface.
      restricts-pushes: false

      # If review dismissal restriction is enabled then only users, teams,
      # or apps specified can dismiss a blocking review.
      #
      # It is not possible for codebase governor to manage the users, teams
      # and apps specified so these need to be manually set in the GitHub
      # interface.
      restricts-review-dismissals: false

If you need any advice on using advanced settings, please use the available support channels.

defaults.readers

The defaults.readers section specifies default readers for capability repositories. A “reader” is a user with read permission to a repository. Don’t specify defaults if you intend to manage protections manually in the GitHub UI or with your own automation.

  • readers.teams lists the teams to grant read access to. Reference using the team “slug” which is the URL identifier for the team within Flutter-Global.
  • readers.users lists the GitHub usernames to grant read access to. Only reference existing members of Flutter-Global.

If you specify reader teams and/or users, then these are the only teams/users with read access. Codebase governor removes any other teams/users with read access.

Requested Contribution Access

Inner source requested contribution access grants all members of Flutter-Global read access:

readers:
  teams: ["all-flutter-global"]

Requested Access

Requested Access grants read permission to a more limited team:

readers:
  teams: ["your-team-1", "your-team-2"]

No Read Access

An empty list specifies that nobody has read access:

readers: {}

defaults.contributors

The defaults.contributors section specifies default contributors for the capability repositories. A “contributor” is a user with write permission to a repository. Don’t specify defaults if you intend to manage protections manually in the GitHub UI or with your own automation.

  • contributors.teams lists the teams to grant write access to. Reference using the team “slug” which is the URL identifier for the team within Flutter-Global.
  • contributors.users lists the GitHub usernames to grant write access to. Only reference existing members of Flutter-Global.

If you specify contributing teams and/or users, then these are the only teams/users with write access. Codebase governor removes any other teams/users with write access.

Open Contribution Access

Inner source open contribution access grants all members of Flutter-Global write access:

contributors:
  teams: ["all-flutter-global"]

Note how you require robust branch protection to maintain a secure workflow – any of the standard branching strategies are suitable for this setup.

Requested Access

Requested Contribution or Requested Access grants write permission to a more limited team:

contributors:
  teams: ["your-team-1", "your-team-2"]

If the contributor group is small, your access request process could simply use pull requests on the configuration to directly manage a list of contributing users:

contributors:
  users:
    - example-user-1
    - example-user-2
    - example-user-3

No Write Access

An empty list specifies that nobody has write access:

contributors: {}

defaults.admins

The defaults.admins section specifies default administrator for the capability repositories. The recommended way to specify repository administrators is to define capability owner and maintainers. Usually you want to enforce no other administrators.

  • admins.teams lists the teams to grant admin access to. Reference using the team “slug” which is the URL identifier for the team within Flutter-Global.
  • admins.users lists the GitHub usernames to grant admin access to. Only reference existing members of Flutter-Global.

If you specify admin teams and/or users, then these along with owner and maintainers are the only teams/users with admin access. Codebase governor removes any other teams/users with admin access.

No Admin Access

To ensure no-one other than owner or maintainers have admin access use an empty object:

admins: {}

Core Team Admins

Several inner source products have a “core team”. Depending on roles and setup, it can be useful for some members of the core team to manage elements of repository access and security which require admin access despite not being an owner or maintainer:

admins:
  teams: ["xyz-core-team-admins"]

defaults.labels

The defaults.labels section enables and specifies the automatic labelling behaviour for PRs and Issues.

defaults.labels.pr-reviewer-division

Add the pull request reviewer division when opening a new pull request.

defaults.labels.issue-author-division

Add the issue creator division when opening a issue.

defaults.labels.pr-size-reminder

Warn the user whenever the labels major, minor and documentation, enhancement, bug have not been applied, via a comment in the pull request.

pr-size-reminder comment example

Examples of the PR and Issue labelling automation can be viewed here.

Examples

Examples can be viewed in the org-config repository.