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. 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:
defaults.branch-protections
defines the default branch protections.defaults.contributors
defines the default repository contributors.defaults.admins
defines the default repository administrators.
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.
branch-protections
expects an array of keys, so you can define as many rules as you need.branch-protections[*].patterns
specifies a list of branch name patterns to apply this rule to.branch-protections[*].parameters
specifies the constraints to apply.
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 withdevelop/
and containing a single slash. You can include multiple slashes withdevelop/**/*
, and you can extend the develop string withdevelop**/**/*
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:
requires-codeowner-reviews
if enabled requires at least one of the approving reviews to be from a GitHub configured “codeowner”.allow-stale-reviews
allows any existing pull request approvals to remain valid even after you push additional commits.allow-admin-bypass
allows repository admins to bypass the protection rule and push directly to the branch.
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.
Examples of the PR and Issue labelling automation can be viewed here.
Examples
Examples can be viewed in the org-config repository.
- The Codebase Governor capability defaults are an example of a default config which enforces code owner reviews on the default
main
branch.