Audited Source

A lightweight source code setup that ensures change history is visible and can be audited, but does not require review or pre-approval to release a change.

Protected Code

Changes are immutable once released with force push or deletion of the main branch prevented.

Quick & Simple

Changes are quickly and easily pushed direct to main or raised for proposed for review in a feature branch.

Optional Review

Whenever useful, review comments and feedback can be gathered before a change in released using a pull request.

Best for documentation, integration test or other supporting repositories where changes don't always need review. Audited source branch protection ensures previous changes are visible and can be audited at any time, but does not require changes to be reviewed before they are released. It uses a simple GitHub Flow or trunk-based development branching model with relaxed branch protection rules.

  • Protected Code
  • Simple
  • Quick
  • Optional Review

Recommended branching model patterns explained in under 7 minutes!

Branching Model

Release your work by either:

  • Commiting directly to main and pushing your work to the GitHub origin. This releases your changes without review.
  • Create 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 gather feedback on your change before making any adjustments and merging your work via the GitHub UI. You can merge your PR at any time as no reviews are required.

Setup

This guide shows you how to setup the audited 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 the all-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 name owner-cap-example-name and the maintainers as maintainers-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. Branch Protection

Add the following to your Codebase Governor repository config file:

branch-protections:
  - patterns: ["main"]

Note if your repository is older and uses master as the default branch, specify that pattern rather than main.

This allows any user with write access to commit and change code directly without review. If the author would like a review they can of course choose one, but this is not required. In this case, branch protection for main is still valuable to protect it from force pushes or deletions that would modify its history. Since this protection preserves the history you can always inspect and revert any change which you retrospectively want to reject.