This document outlines a set of recommendations, which when implemented, will improve the operational security of GitHub repositories. This is not an exhaustive list.
NOTE: Most of the recommendations apply to the default branch of a repository
(usually main). Please see
Which Branches To Protect for more information.
Who Should Follow This?
While most Google open source repositories hosted on GitHub should follow the basic recommendations outlined below, some projects might not be a good fit, e.g.:
- Projects with only one primary contributor
- Projects that sync from google3 to GitHub via Copybara
Wherever possible, workflows should be adjusted to allow following the basic recommendations.
The advanced recommendations are better suited for critical projects and / or mature projects. While they are very powerful, they are often more difficult to implement and integrate into existing workflows.
Side projects should also follow these recommendations, as they will increase the operational security of any project.
Basic Recommendations
Branch Protection
Branch protection must be enabled for the default branch. This prevents a contributor from re-writing the history of the protected branch, maliciously or by accident!
It is also advised to have this enforced for Administrators too.
Require Pull Requests
To ensure that code committed to the default branch goes through adequate review, Pull Requests should be enforced.
This means that all commits have to go through a Pull Request Review before they can be merged.
Required Number Of Approving Reviewers
At least one reviewer should be required to approve a Pull Request. This is comparable to requiring LGTMs in Google3 (see go/change-management-policy).
It might be appropriate for a project to require more than one review. This might be the case for critical projects which take in a lot of third party contributions.
Dismiss stale reviews
Stale reviews should be dismissed. This means that when a commit is added to a Pull Request, the previous approval is revoked. This prevents merging changes that have not been reviewed.
Require Owners Review
GitHub has a similar system to google3's OWNERS. If the project makes use of this, Pull Requests should require reviews from at least one code owner.
Advanced Recommendations
Signed Releases
Signed releases allow users to have greater confidence in software provenance. The Debian Wiki has some good instructions on how to create these.
Require Signed Commits
Signed commits, like signed releases, allow users to have greater confidence in software provenance. Enforcing signed commits is a good way for users of the project to attest that a repository has not been compromised.
Which Branches To Protect
While branch protection provides a lot of benefits, it can also complicate the development workflow. As such, care should be taken when selecting branches to protect. Some good examples are:
- Release branches
- Stable branches
- Main development branch
Dependency Alerts
GitHub also integrates Dependabot to notify maintainers when a vulnerability is found in a dependency. This feature should be enabled in any repository that uses other open source dependencies.
Security Policy
Use the security policy template to add a security policy to your repository.
Follow the recommendations in the OSS Vulnerability Guide to create and maintain a coordinated vulnerability disclosure (CVD) policy.