diff --git a/docs/checks/internal/checks.yaml b/docs/checks/internal/checks.yaml index 406d9871b60..51601c05a55 100644 --- a/docs/checks/internal/checks.yaml +++ b/docs/checks/internal/checks.yaml @@ -154,7 +154,7 @@ checks: status checks before acceptance into a main branch, or preventing rewriting of public history. - Note: The following settings queried by the Branch-Protection check require an admin token: `DismissStaleReviews`, `EnforceAdmin`, `StrictStatusCheck` and `RequireCodeownerReview`. If + Note: The following settings queried by the Branch-Protection check require an admin token: `DismissStaleReviews`, `EnforceAdmins`, `RequireLastPushApproval`, `RequiresStatusChecks` and `UpToDateBeforeMerge`. If the provided token does not have admin access, the check will query the branch settings accessible to non-admins and provide results based only on these settings. Even so, we recommend using a non-admin token, which provides a thorough enough @@ -191,7 +191,7 @@ checks: This test has tiered scoring. Each tier must be fully satisfied to achieve points at the next tier. For example, if you fulfill the Tier 3 checks but do not fulfill all the Tier 2 checks, you will not receive any points for Tier 3. - Note: If Scorecard is run without an administrative access token, the requirements that specify “For administrators” are ignored. + Note: If Scorecard is run without an administrative access token, the requirements that specify “For administrators” can be safely ignored, and scores will be determined as if all such requirements have been met. Tier 1 Requirements (3/10 points): - Prevent force push @@ -199,19 +199,19 @@ checks: - For administrators: Include administrator for review Tier 2 Requirements (6/10 points): - - Required reviewers >=1 - - For administrators: Last push review - - For administrators: Strict status checks (require branches to be up-to-date before merging) + - Require at least 1 reviewer for approval before merging + - For administrators: Require branch to be up to date before merging + - For administrators: Require approval of the most recent reviewable push Tier 3 Requirements (8/10 points): - - Status checks defined + - Require branch to pass at least 1 status check before merging Tier 4 Requirements (9/10 points): - - Required reviewers >= 2 + - Require at least 2 reviewers for approval before merging + - Require review from code owners Tier 5 Requirements (10/10 points): - - For administrators: Dismiss stale reviews - - For administrators: Require CODEOWNER review + - For administrators: Dismiss stale reviews and approvals when new commits are pushed GitLab Integration Status: - GitLab associates releases with commits and not with the branch. Releases are ignored in this portion of the scoring. diff --git a/docs/design/images/branch-protection-settings-admin-token.png b/docs/design/images/branch-protection-settings-admin-token.png new file mode 100644 index 00000000000..5cc0e70599f Binary files /dev/null and b/docs/design/images/branch-protection-settings-admin-token.png differ diff --git a/docs/design/images/branch-protection-settings-non-admin-token.png b/docs/design/images/branch-protection-settings-non-admin-token.png new file mode 100644 index 00000000000..8554fd46d8a Binary files /dev/null and b/docs/design/images/branch-protection-settings-non-admin-token.png differ diff --git a/docs/faq.md b/docs/faq.md index 624e3a4b935..2fd5f6ffb8a 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -15,6 +15,7 @@ This page answers frequently asked questions about Scorecard, including its purp - [Pinned-Dependencies: Will Scorecard detect unpinned dependencies in tests with Dockerfiles?](#pinned-dependencies-will-scorecard-detect-unpinned-dependencies-in-tests-with-dockerfiles) - [Pinned-Dependencies: Can I use version pinning instead of hash pinning?](#pinned-dependencies-can-i-use-version-pinning-instead-of-hash-pinning) - [Signed-Releases: Why sign releases?](#signed-releases-why-sign-releases) + - [Branch-Protection: How to setup a 10/10 branch protection on GitHub?](#branch-protection-how-to-setup-a-1010-branch-protection-on-github) --- @@ -89,3 +90,28 @@ Currently, the main benefit of [signed releases](checks.md#signed-releases) is t However, there are already moves to make it even more relevant. For example, the OpenSSF is working on [implementing signature verification for NPM packages](https://github.blog/2022-08-08-new-request-for-comments-on-improving-npm-security-with-sigstore-is-now-open/) which would allow a consumer to automatically verify if the package they are downloading was generated through a reliable builder and if it is correctly signed. Signing releases already has some relevance and it will soon offer even more security benefits for both consumers and maintainers. + +### Branch-Protection: How to setup a 10/10 branch protection on GitHub? + +To get a 10/10 score for Branch-Protection check using a non-admin token, you should have the following settings for your branches: + +![GitHub's branch protection settings with the following options selected: "Require a pull request before merging", "Require approvals" with 1 approver, "Require review from Code Owners", "Require status checks to pass before merging", "Require branches to be up to date before merging", and have at least one Status Check chosen. All other options are unchecked.](/docs/design/images/branch-protection-settings-non-admin-token.png) + +When using an admin token, Scorecard can verify if a few other important settings are ensured: + +![GitHub's branch protection settings with the following options selected: "Require a pull request before merging", "Require approvals" with 2 approvers, "Dismiss stale pull request approvals when new commits are pushed", "Require review from Code Owners", "Require approval of the most recent reviewable push", "Require status checks to pass before merging", "Require branches to be up to date before merging", have at least one Status Check chosen, and "Do not allow bypassing the above settings". All other options are unchecked.](/docs/design/images/branch-protection-settings-admin-token.png) + +It's important to reiterate that Branch-Protection score is Tier-based. If a setting from Tier 1 is not satisfied, it does not matter that all other settings are met, the score will be truncated up the Tier's maximum. In this case, 3/10. The following table shows the relation between branch protection settings on GitHub and the score Tier: + +| Name | Status | Required only for admin token | Tier | +| -------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------- | ---- | +| Allow force pushes | Disabled | - | 1 | +| Allow deletions | Disabled | - | 1 | +| Do not allow bypassing the above settings | Enabled | Yes | 1 | +| Require a pull request before merging > Require Approvals | Enabled with at least 1 | - | 2 | +| Require status checks to pass before merging > Require branches to be up to date before merging | Enabled | Yes | 2 | +| Require a pull request before merging > Require approval of the most recent reviewable push | Enabled | Yes | 2 | +| Require status checks to pass before merging > Status Checks | At least 1 | - | 3 | +| Require a pull request before merging > Require Approvals | Enabled with at least 2 | - | 4 | +| Require a pull request before merging > Require review from Code Owners | Enabled and has CODEOWNERS file | - | 4 | +| Require a pull request before merging > Dismiss stale pull request approvals when new commits are pushed | Enabled | Yes | 5 |