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.

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.

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

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
integrity-proxy	boolean	No	true	Whether to run the DIFC proxy for pre-agent gh CLI calls. Set to false to disable

Note

repos is a deprecated alias for allowed-repos. Use allowed-repos in new workflows. Run gh aw fix to migrate existing workflows automatically.

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 the blocked-users list and is always denied regardless of the configured threshold.

merged is the strictest configurable level. A pull request qualifies as merged when it has been merged into the target branch. Commits qualify when they are reachable from the default branch. This is useful for workflows that should only act on production content.

approved corresponds to users who have a formal trust relationship with the repository: owners, members, and collaborators. Items in private repositories are automatically elevated to approved (since only collaborators can access them). Recognized platform bots such as dependabot and github-actions also receive approved integrity. Users listed in trusted-users are also elevated to this level. This is the most common choice for public repository workflows.

unapproved includes contributors who have had code merged before, as well as first-time contributors. Appropriate when community participation is welcome and the workflow’s outputs are reviewed before being applied.

none allows all content through. Use this deliberately, with appropriate safeguards, for workflows designed to process untrusted input — such as triage bots or spam detection.

blocked sits below none and represents an explicit negative trust decision. Items at this level are unconditionally denied — even min-integrity: none does not allow them through. See Blocking specific users below.

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

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, 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

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.

tools:
  github:
    min-integrity: approved
    trusted-users:
      - "contractor-1"
      - "partner-dev"

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 set.

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.

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.

Using GitHub Actions expressions

blocked-users, trusted-users, and approval-labels can each accept a GitHub Actions expression instead of a literal array. The expression is evaluated at runtime and should resolve to a comma- or newline-separated list of values.

tools:
  github:
    min-integrity: approved
    blocked-users: ${{ vars.BLOCKED_USERS }}
    trusted-users: ${{ vars.TRUSTED_USERS }}
    approval-labels: ${{ vars.APPROVAL_LABELS }}

This is useful for managing lists centrally via GitHub repository or organization variables rather than duplicating them across workflows.

Effective integrity computation

The gateway computes each item’s effective integrity in this order:

1. Start with the base integrity level from GitHub metadata (author association, merge status, repo visibility).
2. If the author is in blocked-users: effective integrity → blocked (always denied).
3. Else if the author is in trusted-users: effective integrity → max(base, approved).
4. Else if the item has a label in approval-labels: effective integrity → max(base, approved).
5. Else: effective integrity → base.

The min-integrity threshold check is applied after this computation.

Centralized Management via GitHub Variables

Each per-item list (blocked-users, trusted-users, approval-labels) can also be extended centrally using GitHub repository or organization variables. The runtime automatically unions the per-workflow values with the corresponding variable:

Workflow field	GitHub variable
blocked-users	GH_AW_GITHUB_BLOCKED_USERS
trusted-users	GH_AW_GITHUB_TRUSTED_USERS
approval-labels	GH_AW_GITHUB_APPROVAL_LABELS

For example, if a workflow declares blocked-users: ["spam-bot"] and the organization variable GH_AW_GITHUB_BLOCKED_USERS is set to compromised-acct,old-bot, the effective blocked-users list at runtime is ["spam-bot", "compromised-acct", "old-bot"].

Variables are split on commas and newlines, trimmed, and deduplicated. Set these as repository variables (under Settings → Secrets and variables → Actions → Variables) or as organization-level variables to apply them across all workflows.

This mechanism allows a security team to maintain a shared blocked-users list or approval-labels policy without modifying individual workflow files.

Default Behavior

For public repositories, if no min-integrity is configured, the runtime automatically applies min-integrity: approved. This protects public workflows even when additional authentication has not been set up.

For private and internal repositories, no guard policy is applied automatically. Content from all users is accessible by default.

Pre-Agent Integrity Proxy

When a guard policy is configured (min-integrity is set), the compiler injects a DIFC proxy that filters gh CLI calls in pre-agent setup steps. This ensures that custom steps running before the agent see the same integrity-filtered API responses that the agent itself operates under.

The proxy:

• Routes gh CLI calls through integrity filtering using the same MCP gateway container.
• Applies the static guard policy fields (min-integrity and allowed-repos) that are available at compile time.
• Does not apply blocked-users, trusted-users, or approval-labels (those are resolved at runtime after the proxy starts).
• Is automatically started before custom steps and stopped before the MCP gateway starts to avoid double-filtering.

Disabling the proxy

The proxy is enabled by default whenever a guard policy is configured. To disable it, set integrity-proxy: false:

tools:
  github:
    min-integrity: approved
    integrity-proxy: false

This is an opt-out escape hatch for workflows where pre-agent steps should not be filtered — for example, when custom steps need unfiltered API access for setup purposes.

Note

Disabling the proxy only affects pre-agent gh CLI calls. The agent itself always operates under the configured guard policy via the MCP gateway.

Choosing a Level

The right level depends on who you want the agent to see content from:

• Workflows that automate code review or apply changes: merged or approved — only act on trusted content.
• Workflows that respond to maintainers and trusted contributors: approved — a common, safe default for most workflows.
• Community triage or planning workflows: unapproved — allow contributor input while excluding anonymous or first-time interactions.
• Public-data workflows or spam detection: none — see all activity, but ensure the workflow’s outputs are not directly applied without review.

Note

Setting min-integrity: none on a public repository disables the automatic protection. Only use it when the workflow is designed to handle untrusted input.

Examples

Allow only merged content:

tools:
  github:
    allowed-repos: "all"
    min-integrity: merged

Trusted contributors only (typical for a public repository workflow):

tools:
  github:
    min-integrity: approved

Allow all community contributions (for a triage workflow):

tools:
  github:
    min-integrity: unapproved

Explicitly disable filtering on a public repository, apart from blocked users:

tools:
  github:
    min-integrity: none

Scope to specific organizations with integrity filtering:

tools:
  github:
    allowed-repos:
      - "myorg/*"
      - "partner/shared-repo"
    min-integrity: approved

Block specific users while allowing all other content:

tools:
  github:
    min-integrity: none
    blocked-users:
      - "known-spam-bot"

Trust specific external contributors:

tools:
  github:
    min-integrity: approved
    trusted-users:
      - "contractor-1"
      - "partner-dev"

Human-review gate for external contributions:

tools:
  github:
    min-integrity: approved
    approval-labels:
      - "agent-approved"
      - "human-reviewed"

Centrally managed lists via GitHub variables:

tools:
  github:
    min-integrity: approved
    blocked-users: ${{ vars.BLOCKED_USERS }}
    trusted-users: ${{ vars.TRUSTED_USERS }}
    approval-labels: ${{ vars.APPROVAL_LABELS }}

Combined: blocking, trusting, and labeling:

tools:
  github:
    allowed-repos: "all"
    min-integrity: approved
    blocked-users:
      - "known-spam-bot"
    trusted-users:
      - "contractor-1"
    approval-labels:
      - "agent-approved"

Disable the pre-agent integrity proxy:

tools:
  github:
    min-integrity: approved
    integrity-proxy: false

In Logs and Reports

When an item is filtered by the integrity check, the MCP gateway records a DIFC_FILTERED event in the run’s gateway.jsonl log. Each event includes:

• 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.)

When gateway metrics are displayed, filtered events appear in a DIFC Filtered Events table alongside the standard server usage table:

┌────────────────────────────────────────────────────────────────────────────────────┐
│ DIFC Filtered Events                                                               │
├────────────────┬───────────────┬───────────────┬──────────────────────────────────-┤
│ Server         │ Tool          │ User          │ Reason                            │
├────────────────┼───────────────┼───────────────┼───────────────────────────────────┤
│ github         │ list_issues   │ new-user      │ Resource has lower integrity than │
│                │               │               │ agent requires.                   │
└────────────────┴───────────────┴───────────────┴───────────────────────────────────┘

The Total DIFC Filtered count in the summary line shows how many items were suppressed during the run.

Filtering Logs by Integrity Events

To download only runs that had integrity-filtered content, use the --filtered-integrity flag with the logs command:

gh aw logs --filtered-integrity

This is useful when investigating whether your min-integrity configuration is filtering expected content or when tuning the level after observing real traffic patterns.

Related Documentation

• GitHub Tools Reference — Full tools.github configuration
• MCP Gateway — Gateway architecture and log format
• CLI Reference: logs — Downloading and analyzing workflow run logs