Capability Defaults

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

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. If provided, an owner team owner-cap-<capability name> will be created with the specified owner as the only member. This team will be granted administrative rights to all capability repositories. A team is used so the owner can be referenced via this team name in static dependencies like repository CODEOWNERS and still be easily changed.

owner: example-github-username

maintainers

The maintainers key specifies the maintainers of a capability as an array of their GitHub usernames. If provided, a maintainers team maintainers-cap-<capability name> will be created with the specified members. This team will be granted administrative rights 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 cannot be more than 1 paragraph (i.e. cannot 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. Do not specify defaults if you intend to manage protections manually in the GitHub UI or with your own automation.

Audit SDLC

The Audit SDLC is suitable for documentation, integration test or other non-production deployed supporting repositories. This ensures previous changes are visible and can be audited at any time, but does not require changes to be reviewed before they are made.

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

The branch protection parameter defaults are already configured for audit, with allows-force-pushes and allows-deletions settings defaulting to ensure that the history of the branch cannot be modified or deleted. Since the default values are appropriate, the parameters key can simply be omitted.

Service SDLC

The Service SDLC is suitable for production deployed service code repositories where changes MUST be reviewed. Service branching is optimised for Guest Contribution applications where there is a clear owning team.

branch-protections:
  - patterns:
      - "main"
      - "support/*"
    parameters:
      required-reviews-count: 1
      requires-codeowner-reviews: true
      requires-status-checks: true

In this case the default branch (main or on older repos master) and any previous version support branches (support/*) are configured to:

  • Ensure pull requests are used with at least 1 approving review (required-reviews-count: 1).
  • Require a codeowner approval rather than any other user with write permissions (requires-codeowner-reviews: true).
  • Require automated pull request validation checks to pass before a pull request can be merged (requires-status-checks: true).

Multiple Teams SDLC

The Multiple Teams SDLC is suitable for production deployed service code repositories where changes MUST be reviewed. Multiple Teams branching is optimised for Maintainers in Multiple Teams services where there are multiple teams working concurrently on the code.

branch-protections:
  - patterns:
      - "main"
      - "support/*"
    parameters:
      required-reviews-count: 2
      requires-codeowner-reviews: true
      requires-status-checks: true
  - patterns:
      - "*/develop"
      - "*/release/*"
    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
      allows-deletions: true

The default and previous version support branches are configured like the service SDLC to ensure all production deployed code has been reviewed:

  • Ensure pull requests are used with at least 2 approving review (required-reviews-count: 2). This encourages cross team review for critical pull requests.
  • Require a codeowner approval rather than any other user with write permissions (requires-codeowner-reviews: true).
  • Require automated pull request validation checks to pass before a pull request can be merged (requires-status-checks: true).

Develop and release branches also require branch protection, but the settings can be optimised for development speed:

  • maintainers and any other repository admins 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 are made (allow-stale-reviews: true). This means the author spends less time chasing re-reviews after minor edits.
  • A branch which is not up-to-date can still be merged (allow-stale-branch-merge: true). This reduces the time an author spends updating their branch.
  • develop and release branches change over time: teams are added and removed and release branches are explicitally deleted after a release is completed so deleted is allowed via allows-deletions: true.

branch-protections[*].patterns

The branch name pattern that the protection rule will apply to. Due to the GitHub implementation this pattern must be specified 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 does not match directory separators (/). For example, qa/* will match all branches beginning with qa/ and containing a single slash. You can include multiple slashes with qa/**/*, and you can extend the qa string with qa**/**/* 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 specify a rule must apply to default, develop, support and release branches in a multiple team branching model:

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

branch-protections[*].parameters

The protection parameters that will be applied to the specified patterns.

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

The number of required pull request reviews before commits can be merged into this branch. 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 cannot push directly to this branch, instead they need to raise a pull request and get at least 1 review approval from another user with write permission before the branch can be merged.

required-reviews-count: 1

The GitHub docs provide more information about required reviews.

There are several related parameters:

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

Repository “code owners” can be configured in your repository using the CODEOWNERS file. Typically this will reference the capability maintainer team as it then automatically adds them as reviewers when a pull request is raised.

requires-codeowner-reviews: true

The default value for this parameter is false. If enabled by setting it to true, a pull request will require an review approval from the specified code owners before it can be merged. Without this setting enabled, the required-reviews-count can be provided by any user with write access to the repository.

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

By default a pull request approval is dismissed when additional changes are made.

Enabling allow-stale-reviews means a pull request approval remains valid even when additional changes are pushed to the pull request branch after the review. This is convenient for the pull request author as they act on review feedback to implement minor fixes to the pull request – they don’t need to get the pull request re-reviewed after the have pushed their fixes. However, note how it allows additional unreviewed code to be appended to an existing approved pull request so enabling this rule is not recommended for critical branches where all code must be reviewed.

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 are expected 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 ensure that all required GitHub status tests are passing before changes can be merged to a protected branch. GitHub status checks can be GitHub Action workflows or external checks like a divisional Jenkins or SonarCloud.

requires-status-checks: true

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

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

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

Enabling allow-stale-branch-merge allows the status checks to remain valid and the pull request remains mergable even when the pull request branch becomes out of date with the base branch. This allows the pull request to continue when changes are made to the base branch, but does compromise status check guarantees.

allow-stale-branch-merge: true

Example: Nuno and Tiago are each working on separate feature branches. They both raise pull requests to merge their work into main. Nuno’s feature is reviewed and approved quickly and he merges it into main. Tiago’s branch is now out of date with main. Unless allow-stale-branch-merge is enabled Tiago will need to merge Nuno’s changes up from main into his feature branch before his pull request can be merged.

Advanced Settings

Further branch protection settings are described in the GitHub docs and can be configured by:

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.contributors

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

  • contributors.teams specifies a list of teams to grant write access to. The teams are specified by the team “slug” which is the URL identifier for the team. Only teams within Flutter-Global can be referenced.
  • contributors.users specifies a list of GitHub usernames to grant write access to. Only members within Flutter-Global can be referenced.

Note that if contributing teams and/or users are set the codebase governor will ensure that these are the only teams/users with write access to the repository and any other teams/users with write access will be removed.

Inner Source Access

With an inner source access model all members of Flutter-Global are treated as contributors. Therefore all members of the organisation are given write access to the repository by setting the all-flutter-global team as contributors.

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

Note how robust branch protection is required to maintain a secure workflow – any of the standard SDLC examples are suitable for this setup.

Requested Access

With a requested access model you manage your own access request process. If your access request process results in a managed team then you can simply configure this team as the contributors:

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 will be granted write access and anybody with existing write access will be removed.

contributors:
  teams: []

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. It is often beneficial to enforce no other administrators, and there are valid use-cases where additional administrators are required.

  • admins.teams specifies a list of teams to grant admin access to. The teams are specified by the team “slug” which is the URL identifier for the team. Only teams within Flutter-Global can be referenced.
  • admins.users specifies a list of GitHub usernames to grant admin access to. Only members within Flutter-Global can be referenced.

Note that if admins teams and/or users are set the codebase governor will ensure that these along with owner and maintainers are the only teams/users with admin access to the repository. Any other teams/users with admin access will be removed.

No Admin Access

The typical use-case is to ensure no-one other than owner or maintainers have admin access. This can be specified using an empty list. Anybody with existing admin access other than owner or maintainers will be removed.

admins:
  teams: []

Core Team Admins

Several inner source products have a Flutter group “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"]

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

admins:
  users:
    - example-user-1
    - example-user-2

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.