Multiple Team Setup

1. Use Codebase Governor

Manual setup is error-prone, so use Codebase Governor (CBG). This defines access and branch protection using YAML config files in the org-config repository.

• Your repository is probably already configured by CBG – to find out search for your repository in the service catalogue. The catalogue page links to your repository config if already managed. You can update the config in this file by creating a new branch and raising a pull request.
• If there is no existing CBG config you need to start using Codebase Governor. This has an initial learning curve but saves you time especially if you manage many repositories. Support is available from the inner source team.

2. Access Control

Owner and Maintainers

• By configuring your repository with Codebase Governor, it’s part of a group of repositories called a capability.
• The capability name is the directory in which you stored your repository config file in org-config.
• If the capability name was example-name, reference the owner using the owner-cap-example-name team and the maintainers as maintainers-cap-example-name team.
• You define the membership of these teams in the _defaults.yml capability defaults file in the same directory as your repository config file in org-config.
• These teams are automatically granted admin permissions on all repositories within the capability.

Admins, Contributors & Readers

Choose the access model most appropriate to your repository. Apply this access model also through Codebase Governor. For example, to apply the Open Contribution access model:

# enforce no admins other than owner & maintainers
admins: {}

# allow contribution from any member of Flutter-Global
contributors:
  teams:
    - all-flutter-global

3. CODEOWNERS

The CODEOWNERS file in the root directory of your repository has a special meaning in GitHub. To ensure maintainers review changes it must exist and reference the maintainer team using the content:

# replace 'example-name' with your capability name:
*       @Flutter-Global/maintainers-cap-example-name

4. Branch Protection

Add the following to your Codebase Governor repository config file:

branch-protections:
  - patterns:
      - "main"
      - "master"
      - "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 (main or master) and previous version support branches all production require maintainers to approve an changes:

• Ensure pull requests have at least 2 approving reviews (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).

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.

5. Tag Protection

If using semver tags prefixed with a v on the repository to trigger releases and builds you also need to protect them. Create a tag protection rule:

• Use the GitHub web interface to view your repository settings (the “Settings” tab).
• Navigate to the “tags” section.
• Add a tag protection rule using the v* pattern.

6. Create Develop Branches

Each team uses its own team-name/develop branch as part of the multiple teams branching model. To get started you now just need to create these branches, one for each team.

For example to create a develop branch for the opo team:

git checkout main
git checkout -b opo/develop
git push -u origin opo/develop

Examples

Adoption examples are available on this page. You can use these to help you setup this pattern for your own context, and please feel free to contribute to these docs to help others.