mirror of
https://github.com/ossf/scorecard.git
synced 2024-09-11 08:55:27 +03:00
📖 Update Branch-Protection admin and non-admin requirements (#2772)
* docs: Branch protection admin-only requirements Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: Branch protection requirements by tier Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: How get a perfect score in branch protection Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: Fix local images ref in doc Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: Fix typo Co-authored-by: Pedro Nacht <pedro.k.night@gmail.com> Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: Fix check specific table of contents Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * fix: Code owners setting is non admin Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: Fix branch protection applied not only to main branch Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: Add alt text for images Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: You can get a perfect score with non admin access Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: update max tier scores Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: update tier 1 max points explanation Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: Move changes to internal checks doc Move changes done in docs/checks.md to docs/checks/internal/checks.yaml. Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: Revert changes on checks doc Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: Fix admin settings evaluated on branch protection Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: Change branch protection model status checks Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: Change tiers score to expected score The expected score for the code to output is 3/10 for Tier 1 case and 7/10 for Tier 3 case. The scoring issue will be reported as bug. Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> * docs: Fix Tier 3 score Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> --------- Signed-off-by: Gabriela Gutierrez <gabigutierrez@google.com> Co-authored-by: Pedro Nacht <pedro.k.night@gmail.com>
This commit is contained in:
Gabriela Gutierrez
GitHub
parent
10ff05d530
commit
9e28194a67
@ -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.
|
||||
|
||||
BIN
docs/design/images/branch-protection-settings-admin-token.png
Normal file
BIN
docs/design/images/branch-protection-settings-admin-token.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 473 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 473 KiB |
26
docs/faq.md
26
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:
|
||||
|
||||
|
||||
|
||||
When using an admin token, Scorecard can verify if a few other important settings are ensured:
|
||||
|
||||
|
||||
|
||||
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 |
|
||||
|
||||
Loading…
Reference in New Issue
Block a user