It enables the management of repository settings via YAML file config and a secure pull-request workflow ("GitOps") rather than manually in the GitHub UI.
Codebase Governor is automation that:
- groups repositories into “capabilities” to help manage several repositories together.
- defines owner and maintainer teams.
- defines admin and write access to repositories.
- defines branch protection for repositories.
- All config files are in the org-config repository.
- A capability is simply a directory containing repository config files: e.g. the codebase governor capability is
- A repository config file has this YAML format and is named after the repository.
- Capability defaults are defined in a
_defaults.ymlfile in this YAML format. This includes defining an owner and maintainers for the capability.
- Commented file examples of both defaults and repository config files can be found in the codebase governor capability.
- Edit the config by cloning org-config, create a branch and commit your changes then raise a pull request. Your changes will be validated and reviewers added automatically. View closed PRs to see examples.
A “capability” is the way repositories are grouped and organised within Flutter-Global.
- A capability is a group of related repositories that does something meaningful (e.g. a product feature).
- Each GitHub repository is owned by a single capability.
- A capability has a named owner, and a single team of expert maintainers.
- Not all repositories in Flutter-Global are part of a capability, but it is a requirement of using the codebase governor.
Example: The Global Betting Platform is a collection of capabilities that can be used together as a betting platform. Cashout is one of those capabilities. The Cashout capability consists of several repositories related to bet cashout: separate quoting and transacting services, integration test suites and operational reconcilation tools.
A capability is simply defined as a directory in the org-config repository that contains repository config files. The repository config files a capability directory contains are the members of the capability.
codebases/ cashout/ _defaults.yml fcq-service.yml sco-service.yml reactive-kafka-lib.yml
- To create a capability edit the configuration to create a directory
codebases/<your-capability-name>containing the relevant repository config files you want as members of that capability.
- Capability defaults are defined in a
_defaults.ymlfile in this YAML format.
- An owner and group of maintainers for the capability can be defined in these capability defaults.
- Repositories can be added or removed from a capability simply by creating, moving or deleting repository config files in capability directories in org-config.
The previous version of codebase governor used dedicated capability repositories and a configuration file called
codebases.json. In the current version of codebase governor managing your own capability repository is no longer required. All configuration is now in the org-config repository. If you are migrating from v1 an automated workflow is available to help you migrate.
- The config file must be located at
codebases/<capability name>/<repository name>.yml.
- Any settings in this file will be enforced: for example if the file specifies branch protection rules any manual changes to those rules via the GitHub UI will be detected and reverted.
- All settings are optional: any setting which is not specified you can continue to manually manage by the GitHub UI or your own automation.
- Capability defaults will be applied to the repository if they are defined. Any capability default can be overridden if required in the repository config.
- Only one repository config file can be specified for a repository, and a repository can only be a member of one capability. A repo can be transferred from one capability to another simply by moving the repository config file from one capability directory to a different one.
Edit Your Config
As a member of the Flutter-Global org you will automatically be granted write access to the org-config repository. The config from the
main branch will be applied to your repository, so to edit your config you need to make changes to the files in the
org-config follows GitHub Flow so the
main branch is protected and for security reasons you cannot commit and push changes directly to this branch. Instead, create a new branch and make your changes in your own branch. To merge those changes into
main raise a pull request to merge those changes into the
When you raise your pull request your changes will be validated and immediate feedback provided on any errors or problems. In addition the codebase governor will perform a dry run and add a comment to explain the changes you should expect when the pull request is merged. Appropriate reviewers will be added to your pull request depending on what changes you have made. These reviewers will need to approve your request before it can be merged.
Any change you make to your configuration must be approved before the pull request can be merged. The approval rules are:
- No changes will be applied to a repository without the approval of an existing repository administrator.
- No changes to a capability will be applied without the approval of an existing owner or maintainer. If an owner is configured, this approval request will be initially directed to the owner.
- All changes must involve at least 2 people: the author and a different reviewer.
- The inner source team manage the org-config repository, but their approval is not required unless there is no other sensible approval route possible that meets the above requirements.
For example adding a repository to a capability will require the approval of the capability owner and an existing administrator of the repository to be added. If the capability owner is already an admin of the repository to be added, their approval will fulfill both requirements. If the capability owner has raised the pull request to add the repository to the capability their approval is assumed but the pull request will need to be approved by a colleague to fulfill the “2 people involved” requirement. If the capability had no owner or maintainers configured the approval would fallback to the inner source team for approval.
Numerous capability and configuration examples can be viewed in the org-config repository.
- The Codebase Governor capability defaults are an example of a default config which enforces code owner reviews on the default
- The fsc-cbg repository config is an example config which includes branch protection for develop, release and support branches for the multiple teams branching model.