GitHub Integrity Filtering | GitHub Agentic Workflows
Skip to main content GitHub Integrity Filtering Integrity filtering ( tools.github.min-integrity ) controls which GitHub content an agent can access during a workflow run. Rather than filtering by permissions, it filters by trust : the author association of an issue, pull request, or comment, and whether that content has been merged into the main branch. Migrate from lockdown mode Section titled “Migrate from lockdown mode” GitHub lockdown mode has been superseded by integrity filtering.
Replace lockdown: true with min-integrity: approved : # Before (deprecated) tools : github : lockdown : true # After tools : github : min-integrity : approved Replace lockdown: false with min-integrity: none : # Before (deprecated) tools : github : lockdown : false # After tools : github : min-integrity : none How It Works Section titled “How It Works” The MCP gateway intercepts tool calls to GitHub and applies integrity checks to each piece of content returned.
If an item’s integrity level is below the configured minimum, the gateway removes it before the AI engine sees it. This happens transparently — the agent receives a reduced result set, and filtered items are logged as DIFC_FILTERED events for later inspection. Starting with MCP gateway v0.5.0 , proxy responses that cannot be filtered item by item, such as artifact downloads, raw content, and redirects, require resource-level authorization even in filter mode.
These requests can be denied when the configured allow-only policy does not authorize the resource. Starting with MCP gateway v0.5.1 , Actions job logs, security advisory contents, and file contents fetched at explicit SHAs or non-default refs have baseline none integrity. Repository visibility and trusted PR authors do not promote these payloads to approved ; requests can therefore be denied by min-integrity: approved .
MCP gateway v0.5.2 filters nested review-thread comments individually in filter mode, preserving thread and pagination metadata. In strict mode, any denied comment rejects the entire response. Configuration Section titled “Configuration” Set min-integrity under tools.github in your workflow frontmatter: tools: github: min-integrity: approved min-integrity can be specified alone. When allowed-repos is omitted, it defaults to "all" .
If allowed-repos is also specified, both fields must be present. tools: github: allowed-repos: "myorg/*" min-integrity: approved Configuration Reference Section titled “Configuration Reference” All integrity-filtering inputs are specified under tools.github in your workflow frontmatter. The table below summarizes every available field: Field Type Required Default Description min-integrity string Yes (when any guard policy field is used) approved for public repos; none for private Minimum integrity level: merged , approved , unapproved , or none allowed-repos string or array No "all" Repository scope: "all" , "public" , or an array of patterns like ["myorg/*", "partner/repo"] blocked-users array or expression No [] GitHub usernames whose content is unconditionally denied trusted-users array or expression No [] GitHub usernames elevated to approved integrity regardless of author association approval-labels array or expression No [] GitHub label names that promote items to approved integrity refusal-labels array or expression No [] GitHub label names that downgrade items to none integrity, overriding any promotion from trusted-users or approval-labels integrity-proxy boolean No true Whether to run the DIFC proxy for pre-agent gh CLI calls.
Set to false to disable endorsement-reactions array No ["THUMBS_UP", "HEART"] (when integrity-reactions enabled) Reaction types that promote item integrity to approved . Requires features.integrity-reactions: true disapproval-reactions array No ["THUMBS_DOWN", "CONFUSED"] (when integrity-reactions enabled) Reaction types that demote item integrity. Requires features.integrity-reactions: true endorser-min-integrity string No approved (when integrity-reactions enabled) Minimum integrity of the reactor for an endorsement or disapproval to take effect.
Requires features.integrity-reactions: true disapproval-integrity string No none (when integrity-reactions enabled) Integrity level assigned when a qualifying disapproval reaction is added. Requires features.integrity-reactions: true Integrity Levels Section titled “Integrity Levels” The full integrity hierarchy, from highest to lowest: merged > approved > unapproved > none > blocked 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); users listed in trusted-users 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 The four configurable levels ( merged , approved , unapproved , none ) are cumulative and ordered from most restrictive to least.
Setting min-integrity: approved means only items at approved level or higher ( merged ) reach the agent. Items at unapproved or none are filtered out. blocked is not a configurable min-integrity value — it is assigned automatically to items from users in blocked-users and is always denied regardless of the threshold, even when min-integrity: none . See Blocking specific users . Scoping to Repositories Section titled “Scoping to Repositories” allowed-repos defines which repositories the guard policy applies to.
It accepts three forms: "all" — All repositories the token can access (default when omitted). "public" — Only public repositories. An array of patterns — Specific repositories or owner wildcards. tools: github: allowed-repos: - "myorg/*" - "partner/shared-repo" min-integrity: approved Repository patterns must be lowercase and follow one of these formats: Pattern Meaning owner/* All repositories under owner owner/prefix* Repositories under owner whose name starts with prefix owner/repo A single specific repository Adjusting Integrity Per-Item Section titled “Adjusting Integrity Per-Item” Beyond setting a minimum level, you can override integrity for specific authors or labels.
Blocking specific users Section titled “Blocking specific users” blocked-users unconditionally blocks content from listed GitHub usernames, regardless of min-integrity , trusted-users , or any labels. Blocked items receive an effective integrity of blocked (below none ) and are always denied. 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.
Trusting specific users Section titled “Trusting specific users” trusted-users elevates content from listed GitHub usernames to approved integrity, regardless of their author association. This is useful for contractors, partner developers, or external contributors who should be treated as trusted even though GitHub classifies them as CONTRIBUTOR or FIRST_TIME_CONTRIBUTOR . Bot logins such as github-actions[bot] are also valid.
Use the full login, including the [bot] suffix. Trust is configured per author and does not extend to other authors’ comments on a trusted bot’s issue or pull request. Listing a bot does not require lowering min-integrity to none . tools: github: min-integrity: approved trusted-users: - "contractor-1" - "partner-dev" - "github-actions[ bot ]" Trust elevation only raises integrity — it never lowers it. A user already at merged stays at merged . blocked-users always takes precedence: if a user appears in both blocked-users and trusted-users , they are blocked. trusted-users requires min-integrity to be se
The rest of this page is on the live site.