Repository Config

Codebase governor lets you to override capability defaults in a repository config file.

This page explains the format of the Codebase Governor repository config YAML file. The codebase governor runner repository itself has a commented example of this file. All fields are optional so you can add only what you want the codebase governor to enforce – anything you omit you are free to manage manually via the GitHub UI or your own automation.

The 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”.

`description`

The description key contains a description of the repository. 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 is a tool to manage repository access 
  and branch protections.

`branch-protections`

The branch-protections section specifies the required branch protection rules for the repository. If omitted any default branch protection rules from the capability defaults file will be applied. If no defaults are specified you are managing branch protections either manually via the GitHub UI or with your own automation.

branch-protections expects an array of keys, so you can define as many separate 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 that should be applied.

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:

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 additional changes are pushed.
allow-admin-bypass allows repository admins to bypass the protection rule and push directly to the branch.

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

`contributors`

The contributors section specifies who can contribute to your repository. A “contributor” is a user with write permission to the repository. If omitted the default contributors from the capability defaults file will be applied. If no defaults are specified you are managing contributors manually via 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: []

`admins`

The admins section specifies who can administer your repository. 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. If omitted the default admins from the capability defaults file will be applied. If no defaults are specified you are managing administrators manually via the GitHub UI or with your own automation.

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

`labels`

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

`labels.pr-reviewer-division`

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

`labels.issue-author-division`

Add the issue creator division when opening a issue.

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

The fsc-cbg repository config is an example config which includes branch protection for develop, release and support branches for the multiple teams branching model.