Reviewed Source
Simple pull request based workflow where all changes are reviewed by expert code maintainers before release.
-
Protected Code
- All changes are reviewed by codeowners and involve more than 1 person. Protection rules can be adjusted to your requirements.
-
SemVer Support
- SemVer git tags label beta and production builds. Multiple application versions can be supported independently.
-
Simple
- Simple and familar "GitHub Flow" branching model which the GitHub UI is optimised for.
Best for critical production services. Simple feature-branch based workflow which encourages small pull requests and regular release. All changes are reviewed by maintainers. SemVer git tags used to label releases, trigger beta and production builds and enable old version support if needed.
- Protected Code
- SemVer Support
- Simple
- Instantly Familar
Recommended branching model patterns explained in under 7 minutes!
Branching Model
Release your work by creating a new branch named as your wish from main
, commit your work to this branch and then push to the GitHub origin. Create a GitHub pull request to to allow maintainer review of your change before making any adjustments and merging your work via the GitHub UI after their approval.
Setup
This guide shows you how to setup the reviewed source pattern for a repository.
1. Use Codebase Governor
Manual setup of a repository is error-prone, so use the Codebase Governor (“CBG”) tool provided. CBG enforces access and branch protection for repositories 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. If your repository has existing config it will be linked from its catalogue entry. 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 will need to start using this tool. This has a initial learning curve but will save you time especially if you manage many repositories. Support is available from the inner source team.
2. Access Control
With this pattern:
- Your repository visibility is
Internal
. This means all Flutter staff have read access by joining one of the GitHub organisations within the enterprise agreement. - The capability owner and maintainer team are the only users who can administer the repository.
- All members of
Flutter-Global
are treated as contributors who can make code changes without review. To allow this theall-flutter-global
team is granted write permission.
Owner and Maintainers
- By configuring your repository with Codebase Governor, it is already part of a group of repositories called a capability.
- The capability name is the directory in which your repository config file is located in org-config.
- If the capability name was
example-name
, the owner can be referenced using the team nameowner-cap-example-name
and the maintainers asmaintainers-cap-example-name
. - The membership of these teams is defined 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 and Contributors
Add the following to your Codebase Governor repository config file:
# 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 changes are reviewed by maintainers 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"
parameters:
required-reviews-count: 1
requires-codeowner-reviews: true
requires-status-checks: true
Note if your repository is older and uses master
as the default branch, specify that pattern rather than main
.
- 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
).
5. Tag Protection
This pattern uses semver tags prefixed with a v
on the repository to trigger releases and builds. To ensure that these tags are applied correctly their creation is limited to the maintainer team by creating 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.