docs: add integrity.md reference documentation#22044
Conversation
Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com> Agent-Logs-Url: https://github.com/github/gh-aw/sessions/89ab451b-a195-4968-9e91-283883057c76
Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com> Agent-Logs-Url: https://github.com/github/gh-aw/sessions/89ab451b-a195-4968-9e91-283883057c76
- Add 'Adjusting Integrity Per-Item' section covering blocked-users, approval-labels, and effective integrity computation order - Make integrity levels table more precise: mention private repo auto-elevation, trusted bots, non-fork PR treatment - Rename table column to 'What qualifies at this level' and clarify cumulative behavior (approved allows approved AND merged) - Clarify merged level: PRs qualify by merge state, commits by reachability from default branch - Add two new examples: blocked-users and human-review gate - Remove unrelated smoke-codex.lock.yml change - Fix stray character in ASCII table Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Show blocked as a distinct level below none in the hierarchy diagram and levels table. Clarify it is not a configurable min-integrity value but is assigned automatically via blocked-users. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds a new reference page documenting GitHub integrity filtering (min-integrity) behavior, configuration, and how integrity-filtered items appear in gateway logs and CLI reports.
Changes:
- Introduces
docs/reference/integrity.mdexplaining integrity filtering concepts, levels, and defaults - Adds configuration and usage examples for
tools.github.min-integrity - Documents
DIFC_FILTEREDevents and thegh aw logs --filtered-integrityworkflow for investigation
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - **Server**: the MCP server that returned the filtered content | ||
| - **Tool**: the tool call that produced it (e.g., `list_issues`, `get_pull_request`) | ||
| - **User**: the login of the content's author | ||
| - **Reason**: a description such as `"Resource has lower integrity than agent requires."` | ||
| - **Integrity tags**: the tags assigned to the item that caused it to be filtered | ||
| - **Author association**: the GitHub author association (`CONTRIBUTOR`, `FIRST_TIMER`, etc.) |
There was a problem hiding this comment.
In the DIFC_FILTERED event field list, the tool examples (list_issues, get_pull_request) don’t match the tool names used in the CLI’s DIFC parsing/tests (e.g., pull_request_read, issue_read in pkg/cli/gateway_logs_test.go). Consider either using examples that reflect actual tool_name values or wording this generically (“the tool_name value from the log entry”).
| ```text | ||
| ┌────────────────────────────────────────────────────────────────────────────────────┐ | ||
| │ DIFC Filtered Events │ | ||
| ├────────────────┬───────────────┬───────────────┬──────────────────────────────────-┤ |
There was a problem hiding this comment.
The ASCII table border has a stray - character (──────────────────────────────────-┤), which makes the example look malformed. Please replace it with the consistent box-drawing border characters used on the other lines.
| ├────────────────┬───────────────┬───────────────┬──────────────────────────────────-┤ | |
| ├────────────────┬───────────────┬───────────────┬───────────────────────────────────┤ |
| ```aw wrap | ||
| tools: | ||
| github: | ||
| repos: "myorg/*" |
There was a problem hiding this comment.
The example repos: "myorg/*" is not a valid tools.github.repos value. In the workflow schema, repos only accepts the strings "all"/"public" or an array of repo patterns. This example will fail validation unless it is changed to repos: ["myorg/*"] (or use "all"/"public").
| repos: "myorg/*" | |
| repos: ["myorg/*"] |
| | Level | What qualifies at this level | | ||
| |-------|------------------------------| | ||
| | `merged` | Pull requests that have been merged, and commits reachable from the default branch (any author) | | ||
| | `approved` | Objects authored by `OWNER`, `MEMBER`, or `COLLABORATOR`; non-fork PRs on public repos; all items in private repos; trusted platform bots (e.g., dependabot) | | ||
| | `unapproved` | Objects authored by `CONTRIBUTOR` or `FIRST_TIME_CONTRIBUTOR` | | ||
| | `none` | All objects, including `FIRST_TIMER` and users with no association (`NONE`) | | ||
| | `blocked` | Items authored by users in `blocked-users` — always denied, cannot be promoted | |
There was a problem hiding this comment.
The integrity table is not valid Markdown as written (it starts each row with ||, which introduces an empty column and renders inconsistently). Please change it to a standard pipe table (single leading |) so the Level/Criterion columns render correctly across the docs site.
| ## Adjusting Integrity Per-Item | ||
|
|
||
| Beyond setting a minimum level, you can override integrity for specific authors or labels. | ||
|
|
||
| ### Blocking specific users | ||
|
|
||
| `blocked-users` unconditionally blocks content from listed GitHub usernames, regardless of `min-integrity` or any labels. Blocked items receive an effective integrity of `blocked` (below `none`) and are always denied. | ||
|
|
||
| ```aw wrap | ||
| tools: | ||
| github: | ||
| min-integrity: none | ||
| blocked-users: | ||
| - "spam-bot" | ||
| - "compromised-account" | ||
| ``` | ||
|
|
||
| Use this to suppress content from known-bad accounts — automated bots, compromised users, or external contributors pending security review. | ||
|
|
||
| ### Promoting items via labels | ||
|
|
||
| `approval-labels` promotes items bearing any listed GitHub label to `approved` integrity, enabling human-review workflows where a trusted reviewer labels content to signal it is safe for the agent. | ||
|
|
||
| ```aw wrap | ||
| tools: | ||
| github: | ||
| min-integrity: approved | ||
| approval-labels: | ||
| - "human-reviewed" | ||
| - "safe-for-agent" | ||
| ``` | ||
|
|
||
| This is useful when a workflow's `min-integrity` would normally filter out external contributions, but a maintainer can label specific items to let them through. | ||
|
|
||
| Promotion only raises integrity — it never lowers it. An item already at `merged` stays at `merged`. Blocked-user exclusion always takes precedence: a blocked user's items remain blocked even if they carry an approval label. |
There was a problem hiding this comment.
This page introduces an integrity level blocked and config keys blocked-users/approval-labels, but the current workflow schema only allows min-integrity values none|unapproved|approved|merged and does not permit blocked-users or approval-labels under tools.github (schema has additionalProperties: false). As written, these configuration examples would be rejected by validation; either remove these sections/examples or extend the schema+implementation and the GitHub Tools reference to support them.
| | `merged` | Pull requests that have been merged, and commits reachable from the default branch (any author) | | ||
| | `approved` | Objects authored by `OWNER`, `MEMBER`, or `COLLABORATOR`; non-fork PRs on public repos; all items in private repos; trusted platform bots (e.g., dependabot) | | ||
| | `unapproved` | Objects authored by `CONTRIBUTOR` or `FIRST_TIME_CONTRIBUTOR` | | ||
| | `none` | All objects, including `FIRST_TIMER` and users with no association (`NONE`) | |
There was a problem hiding this comment.
The criteria described for approved integrity here (e.g., “non-fork PRs on public repos”, “all items in private repos”, “trusted platform bots”) doesn’t match the existing definition in docs/src/content/docs/reference/github-tools.md where approved is strictly author_association in OWNER|MEMBER|COLLABORATOR (and only four levels are defined). To avoid conflicting documentation, please align the level definitions with the GitHub Tools reference (or update both docs if the behavior has actually changed).
Summary
Adds a new reference page
docs/src/content/docs/reference/integrity.mdthat documents integrity filtering in GitHub Agentic Workflows.What's covered
min-integrityfield undertools.github, with and withoutreposmerged,approved,unapproved,none— with definitions of what each allows through and the underlyingauthor_associationvaluesmin-integrity: approvedfor public repos, no guard for private/internalDIFC_FILTEREDevents appear in gateway metrics, the fields in each event, and the--filtered-integrityCLI flag for filtering runsThe page is placed at sidebar order 680, between Lockdown Mode (660) and GitHub Tools (710).