Audited Source

Audited Source is best for documentation, integration test or other supporting repositories where changes don’t always need review. It ensures previous changes are visible for audit, but doesn’t require review before releasing changes. It uses a simple GitHub Flow or trunk-based development branching model with relaxed branch protection rules.

Branching Model

Release your work by either:

• Committing 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 it doesn’t require review.

Setup

This guide shows you how to setup the audited source pattern for a repository.

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. 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 isn’t 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.