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 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
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 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 section defines default settings for each repository in the capability:
defaults.branch-protectionsdefines the default branch protections.
defaults.contributorsdefines the default repository contributors.
defaults.adminsdefines the default repository administrators.
These defaults can be overridden for individual repositories within the capability in the repository config file.
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-protectionsexpects an array of keys, so you can define as many rules as you need.
branch-protections[*].patternsspecifies a list of branch name patterns to apply this rule to.
branch-protections[*].parametersspecifies the constraints to apply.
Audited Source ensures changes are preserved for audit, but doesn’t require review before releasing changes.
branch-protections: - patterns: ["main"]
allows-deletions settings ensure that you can’t modify or delete branch history. Since the default values are appropriate, you can simply omit the
Reviewed Source is a feature branch based workflow where all changes require a codeowner approval before merging to
branch-protections: - patterns: - "main" parameters: required-reviews-count: 1 requires-codeowner-reviews: true
The default branch (
main or on older repos
- requires a pull request with at least 1 approving review (
- requires a codeowner approval rather than any other user with write permissions (
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 (
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
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
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/*"
The protection parameters that to apply to the specified patterns.
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.
There are several related parameters:
requires-codeowner-reviewsif enabled requires at least one of the approving reviews to be from a GitHub configured “codeowner”.
allow-stale-reviewsallows any existing pull request approvals to remain valid even after you push additional commits.
allow-admin-bypassallows repository admins to bypass the protection rule and push directly to the branch.
You can configure “code owners” using the
CODEOWNERS file. Usually you specify the capability maintainer team as codeowners.
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.
By default additional changes to a pull request branch dismiss any existing approvals.
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.
By default the branch protection rule constraints apply to all users, including repository or organisation administrators.
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.
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.
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.
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.
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.
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 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.teamslists the teams to grant read access to. Reference using the team “slug” which is the URL identifier for the team within Flutter-Global.
readers.userslists 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.
Inner source requested contribution access grants all members of
Flutter-Global read access:
readers: teams: ["all-flutter-global"]
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:
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.teamslists the teams to grant write access to. Reference using the team “slug” which is the URL identifier for the team within Flutter-Global.
contributors.userslists 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.
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.
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:
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.teamslists the teams to grant admin access to. Reference using the team “slug” which is the URL identifier for the team within Flutter-Global.
admins.userslists 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:
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 section enables and specifies the automatic labelling behaviour for PRs and Issues.
Add the pull request reviewer division when opening a new pull request.
Add the issue creator division when opening a issue.
Warn the user whenever the labels
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 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