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.allow-pr-merge-options[*]

Use allow-pr-merge-options to specify which merge options you allow for pull requests. You must allow at least one option, but can allow several or all of them.

  • defaults.allow-pr-merge-options[*].merge-commit: allow merging pull requests using a merge commit.
  • defaults.allow-pr-merge-options[*].squash: allow merging pull requests using a squash commit.
  • defaults.allow-pr-merge-options[*].rebase: allow merging pull requests by rebasing.
allow-pr-merge-options:
  merge-commit: true
  squash: true
  rebase: true

You can learn more about merging strategies in the GitHub documentation.

defaults.suggest-branch-update-in-pr

The suggest-branch-update-in-pr option defines whether the GitHub UI should suggest updating the pull request branch when it’s out of date with the base branch.

suggest-branch-update-in-pr: true

defaults.allow-auto-merge

The allow-auto-merge option specifies whether to allow auto-merging pull requests.

allow-auto-merge: true

defaults.delete-branch-on-merge

The delete-branch-on-merge option specifies whether you want to delete a branch when you merge it.

delete-branch-on-merge: true

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 preserves changes for audit, but doesn’t require review before releasing changes.

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

The default force-push-allowed 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.pull-request-bypassers

Use pull-request-bypassers to define GitHub users, teams or apps that can bypass the branch protection rule and push code to the branch without creating a pull requests.

branch-protections:
  - patterns:
    - main
    parameters:
      required-reviews-count: 2
      pull-request-bypassers:
        users:
          - user-1
        teams:
          - team-1
        apps:
          - app-1

branch-protections[*].parameters.force-push-[*]

There are two, mutually exclusive settings, that control force pushing to protected branches:

  • force-push-allowed to allow users with write access to the repository to force push to the protected branch.
  • force-push-restricted-to to specify GitHub users, teams and apps allowed to override the default GitHub restriction, and enabling them to force push to protected branches.

NOTE: If you enable both force-push-allowed and force-push-restricted-to, the force-push-restricted-to setting takes precedence.

branch-protections:
  - patterns:
    - main
    parameters:
      force-push-allowed: true

OR

branch-protections:
  - patterns:
    - main
    parameters:
      force-push-restricted-to:
        users:
          - user-1
        teams:
          - team-1
        apps:
          - app-1

See the GitHub Docs for more information about force push.

branch-protections[*].parameters.required-status-check-jobs[*]

Define status checks that must pass before merge with required-status-check-jobs. GitHub status checks jobs can be GitHub Action workflows or external checks like a divisional Jenkins pipeline or SonarCloud check.

required-status-check-jobs:
  - context: "JOB_ID_FROM_WORKFLOW_FILE_1"
    app: "APP_SLUG"

This setting allows you to specify a list of status checks that must pass before anyone can merge a pull request. The value is an array of objects, where:

  • context is the JOB ID of the status check. This is the name of the job in the workflow file that defines the status check. See the GitHub docs for more information.
  • app is the slug of the GitHub App that created the status check. The current version supports the following slugs: github-actions, sonarcloud and any. The any slug allows any GitHub App. If you leave this field blank or omit it, and a status check with the same context already exists, Codebase Governor (CBG) will preserve the existing App setting in GitHub and will not modify them.

For example, if you have the following workflow file in your repository:

name: CI
on: [pull_request]

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello, world!"

The JOB ID is build. You can specify this in the required-status-check-jobs parameter as follows:

required-status-check-jobs:
  - context: build
    app: github-actions

In order for a status check’s JOB ID to be valid, you must:

  1. Define the status check within a workflow file in the repository
  2. Configure this workflow file to use the on option set to pull_request
  3. Execute the status check at least once.

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

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

When requiring status checks (required-status-check-jobs) 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

branch-protections[*].parameters.restrict-push-to

Restrict who can push to the matching protected branch with restrict-push-to. When enabled, only users, teams or apps that have been given permission can push to the protected branch. Also, you can only give push access to a protected branch, or give permission to create a matching branch, to users and teams with the write permission to the repository.

branch-protections:
  - patterns:
    - main
    parameters:
      restrict-push-to:
        users:
          - user-1
        teams:
          - team-1
        apps:
          - app-1

More information about restrict who can push to matching branches in the GitHub docs

branch-protections[*].parameters.restrict-push-exclude-create

This setting operates in conjunction with restrict-push-to (referenced above). When enabled, authorized users, teams or apps can push to the corresponding protected branch. However, they are not permitted to create new branches from this protected branch.

branch-protections:
  - patterns:
    - main
    parameters:
      restrict-push-exclude-create: true
      restrict-push-to:
        users:
          - user-1
        teams:
          - team-1
        apps:
          - app-1

More information about restrict who can push to matching branches in the GitHub docs

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
      allow-admin-bypass: true
      allow-stale-reviews: true
      allow-stale-branch-merge: true

      # Allows you to specify a list of status checks that must pass before 
      # anyone can merge a pull request
      required-status-check-jobs:
        - context: build
          app: github-actions

      # Restricts who can push to the matching protected branch
      restrict-push-to:
        users:
          - user-1
        teams:
          - team-1
        apps:
          - app-1
      # When enabled, authorized users or teams can push to the corresponding 
      # protected branch. However, they are not permitted to create new branches 
      # from this protected branch.
      restrict-push-exclude-create: true

      # Allows the last person to push to a branch to review their own
      # change. Note that if enabled there are cases where a user can 
      # self-approve their own changes.
      allow-last-pusher-to-approve: 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':
      force-push-allowed: 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

Examples can be viewed in the org-config repository.