Repository Config

Codebase Governor lets you to override capability defaults in a repository config 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 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 can’t be more than 1 paragraph (i.e. can’t contain any line breaks).

description: >
  Codebase Governor is a tool to manage repository access 
  and branch protections.

is-template

The is-template key is a boolean that specifies if the repository is a template. If true, the repository will be available to be referenced and used as template to users with permissions to access it when creating new repositories.

is-template: true

using-template

The using-template key specifies the template to use when creating a new repository. The template repository must have the is-template key set to true in their configuration file and the user needs to have permissions to access it.

using-template: <repository_name>

unsafe-admins

The unsafe-admins key grants continuous admin permissions to a specific user.

  • unsafe-admins.users lists the GitHub usernames to grant permanent unsafe admin access. Only reference existing members of Flutter-Global.
  • unsafe-admins.teams lists the teams to grant permanent unsafe admin access. Reference using the team “slug” which is the URL identifier for the team within Flutter-Global.
# The example-username user needs to keep always on admin because ...
unsafe-admins:
  users:
    - example-username
  teams:
    - example-teamname

trusted-committers

The trusted-committers key specifies the trusted committers of a repository as an array of their GitHub usernames. The GitHub trusted committers team trusted-committers-<repository name> has these users as the only members. This team will be added to the repository with admin-on-demand permissions.

trusted-committers:
  - example-username-1
  - example-username-2

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.

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

For more information on merging strategies, please refer to the GitHub Docs.

Details

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

allow-auto-merge

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

allow-auto-merge: true

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

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 apply. If you specify no defaults you are managing branch protections either manually via 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 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

For more information on allowing force pushes, please refer to the GitHub docs.

Details

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.

For more information about requiring status checks in pull requests, please refer to the GitHub docs.

Details

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 with permission can push to or merge into the protected branch. Those with push permission will still need to create a pull request if the branch is protected. 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

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

For more information about restricting who can push to matching branches, please refer to the GitHub docs.

Details

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

For any advice on using advanced settings, please refer to the available support channels.

Details

readers

The readers section specifies who can read your repository. A “reader” is a user with read permission. If omitted the default readers from the capability defaults file apply. If no defaults apply you are managing readers manually via 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: {}

contributors

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

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: {}

admins

The admins section specifies who can administer your repository. The recommended way to specify repository administrators is to define capability owner and maintainers. Usually you want to enforce no other administrators. If omitted the default admins from the capability defaults file apply. If no defaults apply you are managing administrators manually via the GitHub UI or with your own automation.

  • 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"]

apps

The apps section lists the GitHub Apps that should have access to the repository. If needed, you can override the capability defaults by specifying a different list of apps here or an empty one (apps: {}) for none.

  • Each app listed here will be granted access to the repository with the permissions defined in its configuration file.
  • Specify each app using its GitHub App “slug” matching the filename (without extension) of the app’s configuration file in the apps directory of the org-config repository.

This ensures consistent app management across all repositories.

apps:
  - example-app
  - another-app

labels

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

labels:
  - bug
  - enhancement
  - documentation
## `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](/docs/cbg/pr-size-reminder-example.png)

## `custom-properties`

The `custom-properties` section specifies custom properties for the repository. Custom properties allow you to add metadata to repositories for classification and filtering.

**Important**: Repository-level custom properties completely override any defaults from the [capability defaults file][default-config] - there is no inheritance or merging. If you define any custom properties at the repository level, you must explicitly include all desired properties.

```yaml
defaults:
  custom-properties:
    environment: "development"
    team: "backend"
    is-active: true
    technologies: ["golang", "react"]
    compliance-required: false

Supported property types:

  • Text/String: Simple text values ("development")
  • True/False: Boolean values (true or false)
  • Single Select: One value from org-defined options ("production")
  • Multi Select: Multiple values from org-defined options (["golang", "react"])

If omitted, the repository inherits all custom properties from the capability defaults file. If no defaults are specified, the repository will have no custom properties managed by CBG.

Override Behavior Examples

Complete Override:

# _defaults.yml has: environment, team, is-active
# Repository config:
custom-properties:
  environment: "production"  # Override default
  priority: "high"           # Add new property
# Result: Repository gets ONLY environment and priority
# team and is-active from defaults are NOT inherited

Remove All Defaults:

custom-properties: {}  # Removes all default properties

Inherit All Defaults:

# Omit custom-properties section entirely
# Repository inherits all properties from defaults

Custom properties must be created at the organization level before they can be assigned to repositories. See the capability defaults documentation for more information about defining default properties.

Examples

Examples can be viewed in the org-config repository.