docs: add integrity filtering reference and blocked-users/approval-labels to README#2250
docs: add integrity filtering reference and blocked-users/approval-labels to README#2250
Conversation
…bels to README - Add blocked-users and approval-labels options to allow-only policy docs - Add blocked integrity level (below none) to min-integrity list - Reorder integrity levels from highest to lowest for clarity - Add example config with blocked-users and approval-labels - Add link to Integrity Filtering Reference in Further Reading table - Note that approval-labels elevate to approved via max(base, approved) - Note that blocked-users override is unconditional and not overridable Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Updates the README Guard Policies documentation to reflect recent GitHub-guard integrity filtering features (blocked users, approval labels) and adds a link to the external Integrity Filtering Reference.
Changes:
- Expands
allow-onlypolicy docs to includeblocked-users,approval-labels, and theblockedintegrity level. - Reorders and clarifies integrity level descriptions and adds a more complete example config snippet.
- Adds “Integrity Filtering” to the Further Reading links.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - `"unapproved"` — Contributors (CONTRIBUTOR, FIRST_TIME_CONTRIBUTOR) | ||
| - `"approved"` — Members (OWNER, MEMBER, COLLABORATOR) | ||
| **`min-integrity`** — Minimum integrity level required for content items. Levels from highest to lowest: | ||
| - `"merged"` — Objects reachable from main branch |
There was a problem hiding this comment.
The description of the "merged" integrity level as “Objects reachable from main branch” doesn’t match the current guard behavior: merged is applied to merged PRs and to commits in default-branch context (including get_commit by SHA, which may not be reachable from the default branch). Please reword this line to reflect the actual semantics so readers don’t infer a stronger guarantee than the implementation provides.
| - `"merged"` — Objects reachable from main branch | |
| - `"merged"` — Content associated with merged pull requests and operations in default-branch context (for example, commits fetched by SHA while working against the default branch) |
| - `"approved"` — Members (OWNER, MEMBER, COLLABORATOR); private repo items; trusted bots | ||
| - `"unapproved"` — Contributors (CONTRIBUTOR, FIRST_TIME_CONTRIBUTOR) | ||
| - `"none"` — All objects (FIRST_TIMER, NONE) | ||
| - `blocked` — Items from `blocked-users` (always denied; not a configurable value) |
There was a problem hiding this comment.
The integrity level list mixes quoted string values ("none", "approved", etc.) with an unquoted blocked. Since blocked is still an integrity level string (even though it’s not a valid min-integrity value), this formatting can be confusing. Consider formatting it consistently (e.g., "blocked") and explicitly stating it’s not allowed as a min-integrity setting.
| - `blocked` — Items from `blocked-users` (always denied; not a configurable value) | |
| - `"blocked"` — Items from `blocked-users` (always denied; derived integrity only; not allowed as a `min-integrity` setting) |
Changes
Updates the README Guard Policies section to document the new integrity features:
Added
blocked-usersoption — array of usernames whose content gets unconditionalblockedintegrity (belownone)approval-labelsoption — array of labels that elevate items toapprovedintegrity (human-review gate)blockedintegrity level in themin-integrityhierarchyImproved
approvedRelated