Skip to content
Merged
7 changes: 7 additions & 0 deletions .changeset/strict-pull-request-target-bounded-forks.md

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,17 @@ and mixed edits continue to require write-or-higher repository permission.

### Breaking changes

`pull_request_target` workflows now default to same-repository PRs only in both
strict and non-strict mode. Omitting `forks` is equivalent to `forks: []`; no
explicit empty list is required. To admit forks, configure exact `owner/repo`
entries or deliberately trusted `owner/*` patterns, then recompile. Explicit
`"*"` permits unrestricted admission in both modes; strict mode warns and
recommends restricting forks instead of rejecting compilation. Strict mode still
rejects expressions and unsupported pattern forms. Actor
authorization and trusted-checkout restrictions remain mandatory in strict mode;
`acknowledge-risk`, disabled checkout, and trusted checkout policies do not bypass
fork-pattern validation or suppress the unrestricted-forks warning.

The `gh aw outcomes` command has been removed. Use `gh aw logs --outcomes`
to evaluate selected runs, or pipe a run ID to
`gh aw logs --stdin --repo owner/repo --outcomes`. JSON reports now carry
Expand Down
56 changes: 56 additions & 0 deletions docs/adr/72579-apply-fork-filters-to-pull-request-target.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# ADR-72579: Compile PR Fork Filters With Same-Repository Defaults

**Date**: 2026-10-27
**Status**: Proposed
**Deciders**: Unknown (PR #72579)

---

### Context

gh-aw supports compiler-only `forks:` filters under both PR events and label-name filters (`names:`) under `on.pull_request`; these belong in job conditions, not native GitHub Actions trigger properties. The on-section cleanup state machine (`pkg/workflow/frontmatter_on_section_cleanup.go`) checked for the next event before leaving compiler-only subsections such as `on.permissions`, `on.steps`, or `on.skip-author-associations`, so filters after those fields could leak into lock files and fail Actions schema validation. Separately, `applyPullRequestForkFilter` (`pkg/workflow/filters.go`) read only `on.pull_request`, silently ignoring explicit `pull_request_target.forks` restrictions.

Security review also identified that omitted target fork filters previously admitted arbitrary forks, like `"*"`. Trusted actor authorization is insufficient: a maintainer can label an attacker-controlled PR, and an agent can consume malicious PR content with privileged capabilities even when checkout is disabled. The target event therefore needs the same same-repository default as `pull_request`, and strict mode should warn on explicitly unrestricted admission independently of actor authorization, checkout policy, and risk acknowledgment.

### Decision

The compiler will apply fork filters to both `pull_request` and `pull_request_target` using event-scoped job conditions (`github.event_name != '<event>' || ...`), while preserving existing conditions and commenting out processed trigger fields. For `pull_request_target`, omission and `forks: []` both admit only same-repository PRs, in strict and non-strict mode, including scalar trigger shorthand. Explicit patterns always admit same-repository PRs. Target workflows may admit forks through exact `owner/repo` entries or deliberately trusted `owner/*` patterns. Explicit `"*"` permits unrestricted admission in both modes; strict mode warns and recommends restricting forks instead of rejecting compilation. Neither `acknowledge-risk` nor trusted/disabled checkout suppresses that warning. Actor authorization and checkout restrictions remain mandatory, and strict mode still rejects expressions and unsupported pattern forms. The same-repository default for configured `pull_request` event objects is unchanged.

The supported frontmatter schema in `pkg/parser/schemas/main_workflow_schema.json` accepts string and list patterns for both events, but accepts the `forks: {author-association: [...]}` form from [ADR-69374](69374-fork-pr-admission-by-author-association.md) only for `pull_request`; the shared helper's ability to process that object does not make it supported for `pull_request_target`, and this decision does not extend the schema. To produce valid lock files without silently dropping configured admission rules, the cleanup state machine will leave compiler-only subsections before detecting the next event and track `forks` indentation for nested content, including the supported two-space and four-space event layouts.

### Alternatives Considered

#### Alternative 1: Reject `forks:` under `pull_request_target` at schema/compile time

The compiler could treat `forks` as a `pull_request`-only key and raise an error when it appears under `pull_request_target`. That would also stop the silent drop. It was rejected because the field is documented and useful: authors of `pull_request_target` workflows sometimes want to admit only specific fork owners. An error would take away that control instead of providing it.

#### Alternative 2: Require an explicit empty fork list in strict mode

Requiring `forks: []` would make every strict target workflow state its admission policy. It was rejected because omission can enforce the same same-repository-only condition without redundant configuration. The compiler must emit that condition rather than merely accept omission in validation.

#### Alternative 3: Fix only the cleanup leak and keep `pull_request`-only fork filtering

A narrower bug fix would remove the leaked keys and leave admission logic alone. It was rejected because removing `forks` from `pull_request_target` without compiling it into a condition would make the silent drop permanent. The author would get a lock file that looks valid but does not enforce the restriction they configured.

#### Alternative 4: Reject unrestricted fork admission in strict mode

Rejecting `"*"` would force bounded admission, but would also prevent existing explicitly unrestricted workflows from compiling. A strict-mode warning preserves that explicit choice while recommending narrower fork trust and retaining actor and checkout safeguards.

### Consequences

#### Positive
- Recognizing PR events after compiler-only `on.*` fields prevents `forks`/`names` from leaking into native triggers and failing Actions schema validation.
- An explicit `forks:` pattern under `pull_request_target` is now enforced as an event-scoped job condition instead of being ignored.
- Event-scoped guards let workflows that set both PR events use independent fork filters, and existing `if:` and label (`names`) conditions are kept.
- Strict-mode target workflows warn on explicitly unrestricted fork admission, including with risk acknowledgment or checkout exemptions.

#### Negative
- Existing target workflows that omitted `forks` and relied on unrestricted admission must configure the intended fork patterns and recompile. This is documented as a breaking change.
- Recompiling workflows that already had a `forks:` key under `pull_request_target` will start enforcing it. This could stop runs that previously, and unintentionally, admitted all forks.
- The line-oriented cleanup state machine depends on event-ordering logic and indent tracking, which remain fragile compared with editing the YAML AST.
- The author-association object form remains unavailable for `pull_request_target`, despite the shared helper accepting it internally.

#### Neutral
- The [trigger reference](../src/content/docs/reference/triggers.md) describes the `pull_request_target` pattern-filter semantics explicitly.
- Regression tests in `pkg/workflow/filters_forks_test.go`, `pkg/workflow/frontmatter_on_section_cleanup_test.go`, and `pkg/workflow/pull_request_target_forks_test.go` cover fork conditions, generated Actions schema validation, compiler-only field ordering, indentation, strict pattern validation, same-repository defaults, and wildcard warnings without weakening actor or checkout checks.
- Fork admission does not grant permissions or secrets and does not make checking out or executing untrusted fork code safe.
3 changes: 2 additions & 1 deletion docs/src/content/docs/reference/checkout.md
Original file line number Diff line number Diff line change
Expand Up @@ -263,6 +263,7 @@ on:
pull_request_target:
types: [closed]
branches: [main]
forks: ["dotnet/*"]
acknowledge-risk: true
allowed-checkouts:
- repository: dotnet/AspNetCore.Docs
Expand All @@ -278,7 +279,7 @@ checkout:

`on.pull_request_target.allowed-checkouts` defaults to no additional trusted checkouts. Each entry requires a literal `owner/repository` and a non-empty literal branch, tag, or commit SHA. Matching is exact and case-sensitive; repository/ref pairs cannot be combined across entries. Expressions, wildcards, and `refs/pull/...` refs are rejected in the policy. Every configured checkout must independently satisfy the policy or the existing base-checkout rules. Do not configure `checkout.fetch` for these checkouts: follow-up fetches can add refs beyond the trusted checkout, so they do not satisfy the policy. External repositories with omitted or PR-dependent refs remain rejected. Wiki checkouts are not covered by this allowlist.

`on.pull_request_target.acknowledge-risk` defaults to `false`. Setting it to `true` suppresses **only** the strict-mode dangerous-trigger warning, including for `checkout: false` or a supported base checkout. It neither allows other checkouts nor disables unrelated warnings, strict validation, or safe-update checks. An allowlist without acknowledgment still emits the trigger warning.
`on.pull_request_target.acknowledge-risk` defaults to `false`. Setting it to `true` suppresses **only** the strict-mode dangerous-trigger warning, including for `checkout: false` or a supported base checkout. It neither allows other checkouts nor bypasses [fork-pattern validation](/gh-aw/reference/triggers/#fork-filtering-forks), actor authorization, the unrestricted-forks warning, other strict validation, or safe-update checks. An allowlist without acknowledgment still emits the trigger warning.

> [!CAUTION]
> This policy records maintainer trust, not proof that checked-out code is safe. Prefer immutable commit SHAs; literal branches and tags can move. Keep workflow code and helpers on trusted base refs, read source PR changes as data, and never execute PR-controlled code with privileged credentials. Checkout authentication (`github-app` or `github-token`) and safe-output publication must still be configured separately. This example illustrates compilation policy, not runtime authentication or publication validation.
Expand Down
15 changes: 11 additions & 4 deletions docs/src/content/docs/reference/frontmatter-full.md
Original file line number Diff line number Diff line change
Expand Up @@ -793,9 +793,15 @@ on:
# (optional)
draft: true

# When true, allows workflow to run on pull requests from forked repositories with
# write permissions. Security consideration: use cautiously as fork PRs run with
# base repository permissions.
# Filter fork pull requests by repository pattern (string or list). Omission and
# an empty list both allow only same-repository PRs. Exact owner/repo entries or
# trusted owner/* patterns admit matching forks; '*' allows all forks. Strict mode
# warns on any '*' entry and recommends narrower admission, but compilation
# continues. Strict mode rejects expressions and unsupported pattern forms.
# Same-repository PRs remain allowed. Actor authorization and checkout
# restrictions remain mandatory in strict mode; acknowledge-risk neither bypasses
# them nor suppresses the fork warning. This does not change GitHub's
# base-repository permissions or secret availability for pull_request_target.
# (optional)
# Accepted formats:

Expand All @@ -807,7 +813,8 @@ on:
# Array items: string

# Acknowledge elevated permissions and secret access to suppress only the
# strict-mode pull_request_target trigger warning. Checkout validation remains
# strict-mode pull_request_target trigger warning. The unrestricted-forks warning,
# actor authorization, fork-pattern validation, and checkout validation remain
# enforced.
# (optional)
acknowledge-risk: true
Expand Down
6 changes: 5 additions & 1 deletion docs/src/content/docs/reference/triggers.md
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ GitHub's fork-contributor workflow approval setting does not protect `pull_reque

#### Fork Filtering (`forks:`)

Pull request workflows block forks by default for security. Use the `forks:` field to allow specific fork patterns:
`pull_request` workflows block forks by default for security. Use the `forks:` field to allow specific fork patterns:

```yaml wrap
on:
Expand All @@ -207,6 +207,10 @@ Use `["owner/repo"]` for a specific repository, `["owner/*"]` for an entire org/

Alternatively, use `forks: {author-association: [OWNER, MEMBER, COLLABORATOR]}` to allow fork PRs by the author's relationship to the base repository rather than the fork owner. Same-repository PRs remain allowed, and no association is implicitly included. See [author associations](/gh-aw/reference/fork-support/#author-associations) for trust and secret-availability considerations.

`pull_request_target` also defaults to same-repository PRs only: omitting `forks:` is equivalent to `forks: []` in both strict and non-strict mode. To admit specific forks, list exact `owner/repo` entries or deliberately trusted `owner/*` patterns. Same-repository PRs remain allowed. `"*"` anywhere in a list permits all forks; strict mode warns and recommends restricting fork admission instead of rejecting compilation. `acknowledge-risk: true`, disabled checkout, and trusted checkouts do not suppress this fork warning. Actor authorization and checkout restrictions remain enforced independently; strict mode still rejects expressions and unsupported pattern forms.

Fork filters and `pull_request.names` compile into job conditions, not GitHub Actions trigger properties. Bounded fork admission is defense in depth, not proof of safe PR content: a trusted actor can label an attacker-controlled PR, and disabling checkout does not prevent an agent from reading malicious content with privileged capabilities.

#### Stacked PR Filtering (`max-stack:`)

When using stacked pull requests (a chain of PRs each targeting the previous one), every PR in the stack normally triggers workflows. This multiplies CI cost for identical changes being reviewed at multiple layers. The `max-stack:` field lets you limit which stack layers run the workflow.
Expand Down
2 changes: 0 additions & 2 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -244,8 +244,6 @@ golang.org/x/exp v0.0.0-20240909161429-701f63a606c0 h1:e66Fs6Z+fZTbFBAxKfP3PALWB
golang.org/x/exp v0.0.0-20240909161429-701f63a606c0/go.mod h1:2TbTHSBQa924w8M6Xs1QcRcFwyucIwBGpK1p2f1YFFY=
golang.org/x/mod v0.42.0 h1:ICeL3t2L30ljSPHHxDnR4fqVcBt/zR2zJAb9juavmQg=
golang.org/x/mod v0.42.0/go.mod h1:u5fzIrRInkL8MaO1cbRkUHT64v303YIT5KEqpNr7jRs=
golang.org/x/net v0.61.0 h1:RR+6j/BTBCrggOLugxa+66R8FvoN6MHlzDlZIbN9YFw=
golang.org/x/net v0.61.0/go.mod h1:WgDCOTH8iwtB66T4/GfI94AHo/hhdb7Hah9NDseQfiI=
golang.org/x/net v0.62.0 h1:18ELalfM5+XNRwzM2nYqXsZQ9ByS1uhj2O/U7+5jqRY=
golang.org/x/net v0.62.0/go.mod h1:WgDCOTH8iwtB66T4/GfI94AHo/hhdb7Hah9NDseQfiI=
golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
Expand Down
4 changes: 2 additions & 2 deletions pkg/parser/schemas/main_workflow_schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -2044,12 +2044,12 @@
}
}
],
"description": "When true, allows workflow to run on pull requests from forked repositories with write permissions. Security consideration: use cautiously as fork PRs run with base repository permissions."
"description": "Filter fork pull requests by repository pattern (string or list). Omission and an empty list both allow only same-repository PRs. Exact owner/repo entries or trusted owner/* patterns admit matching forks; '*' allows all forks. Strict mode warns on any '*' entry and recommends narrower admission, but compilation continues. Strict mode rejects expressions and unsupported pattern forms. Same-repository PRs remain allowed. Actor authorization and checkout restrictions remain mandatory in strict mode; acknowledge-risk neither bypasses them nor suppresses the fork warning. This does not change GitHub's base-repository permissions or secret availability for pull_request_target."
},
"acknowledge-risk": {
"type": "boolean",
"default": false,
"description": "Acknowledge elevated permissions and secret access to suppress only the strict-mode pull_request_target trigger warning. Checkout validation remains enforced."
"description": "Acknowledge elevated permissions and secret access to suppress only the strict-mode pull_request_target trigger warning. The unrestricted-forks warning, actor authorization, fork-pattern validation, and checkout validation remain enforced."
},
"allowed-checkouts": {
"type": "array",
Expand Down
Loading
Loading