Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/aw/syntax-checkout.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ checkout:

- `repository:` / `repo:` (alias) - Repository in `owner/repo` format (defaults to current repository). Without `multi: true`, must resolve to exactly one repository; wildcards are not supported.
- `ref:` - Branch, tag, or SHA to check out (defaults to the triggering ref)
- `data-only:` - Literal boolean, default `false`. Self-attests that trusted host tooling consumes a separate checkout only as data and suppresses only that checkout's ref warning. It does not enforce isolation or change execution, and does not suppress the default workspace checkout warning. Every merged request for the same target must set `true`.
- `path:` - Relative path within `GITHUB_WORKSPACE` (defaults to workspace root). In `multi: true` mode this is a literal prefix: repositories land under `prefix/owner/repo`.
- `fetch-depth:` - Number of commits to fetch; `0` = full history, `1` = shallow (default). When multiple configs target the same path, the deepest value wins.
- `fetch:` - Additional Git refs to fetch after checkout (string or array of patterns)
Expand Down
49 changes: 49 additions & 0 deletions docs/adr/76806-data-only-checkout-acknowledgement.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# ADR-76806: Data-Only Checkout Acknowledgement for Checkout-Ref Warnings

**Date**: 2026-11-11
**Status**: Draft
**Deciders**: pelikhan (PR actor) and gh-aw maintainers; review pending [TODO: verify]

---

### Context

[ADR-74951](74951-warn-on-dynamic-checkout-ref-with-host-steps.md) added a compile-time warning when a `checkout.ref` is a dynamic expression (`needs.*`, `github.event.*`, or `inputs.*`) and host steps run after that checkout. Host steps run outside the agent sandbox and may execute code from the selected ref. Issue #76586 describes a workflow where trusted tooling is checked out from the default branch and a dynamically selected content repository is read only as data; the warning fires even though no code from that checkout runs. Authors need a supported way to record this separation without removing validation or suppressing unrelated diagnostics. The compiler cannot verify data-only use, because a `working-directory` value does not show which checkout a command reads or executes.

### Decision

We will add a literal boolean `data-only` option (default `false`) to each `checkout:` entry. When it is `true`, it suppresses only that checkout's checkout-ref warning. When several requests merge into the same checkout target, the target stays acknowledged only if every request sets `data-only: true`. The option is an author acknowledgement, not enforced isolation: it does not change checkout steps, credentials, permissions, or other diagnostics. The primary driver is keeping the warning active for unacknowledged checkouts while giving authors a narrowly scoped way to record intent.

### Alternatives Considered

#### Alternative 1: Check out the dynamic ref after host steps

ADR-74951 documents a "check out the default branch, run setup, then switch refs" pattern, and the reporter says they would prefer to follow the recommended pattern. This was not sufficient on its own: the example runs tooling against the target checkout in the same job (`./scripts/validate-content ../target`), so the target must exist before the host step runs. Restructuring into separate jobs or artifacts is possible, but it is a larger workflow change than a diagnostic warning justifies. This was a close call.

#### Alternative 2: Disable the checkout-ref warning globally

A single switch that disables the warning would be simple to implement. It would also hide the warning for every checkout, including checkouts that really do run untrusted code on the host. The reporter explicitly asked not to suppress unrelated diagnostics, so this was rejected.

#### Alternative 3: Infer data-only use from `working-directory` or step usage

The compiler could treat a checkout as data-only when no step runs inside it. This is unreliable: the documented example runs a script in `tooling` that reads `../target`, and commands can execute code outside their working directory. Inference would silence warnings for checkouts that may run code, so it was rejected.

### Consequences

#### Positive
- Authors can record tooling/data separation and silence only the warning that does not apply, while other checkouts keep their warnings (covered by merged-checkout tests).
- Generated checkout steps are unchanged, so the option carries no runtime or credential risk (`TestCheckoutDataOnlyPreservesCheckoutSteps`).
- The merge rule fails safe: an unacknowledged duplicate request keeps the warning on.

#### Negative
- The acknowledgement is unverified. An incorrect `data-only: true` silences a warning that may indicate real risk, and the compiler does not check it.
- The option adds a frontmatter key, a schema entry, and a documentation section that must stay consistent with the warning text.
- Whether a warning fires now depends on every merged request for a target, which is harder to predict for imported workflows.

#### Neutral
- Existing workflows compile to the same checkout YAML; the only user-visible change is the warning text, which now mentions trusted tooling refs and `data-only`.
- This refines the scope of ADR-74951's warning rather than replacing its decision. The warning remains the default.

---

*ADR created by [adr-writer agent]. Review and finalize before changing status from Draft to Accepted.*
22 changes: 22 additions & 0 deletions docs/src/content/docs/reference/checkout.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,27 @@ The relevant agent-job order is:

Keep the agent workspace on a trusted ref and, when needed, fetch untrusted refs only to inspect their contents as data. Do not switch the host workspace to an untrusted branch or run its scripts: a manual checkout can execute Git hooks and can expose branch-controlled agent configuration. For PR-head work, use compiler-managed automatic PR checkout so the trusted agent configuration is restored; disabling that checkout also disables its paired configuration restore.

### Separate Tooling and Data Checkouts

When trusted host tooling processes a separate checkout only as data, `data-only: true` acknowledges that separation and suppresses the checkout-ref warning for that checkout:

```aw wrap
checkout:
- path: tooling
ref: ${{ github.event.repository.default_branch }}
- repository: example-org/content
ref: ${{ needs.prepare.outputs.branch }}
path: target
data-only: true
steps:
- working-directory: tooling
run: ./scripts/validate-content ../target
```

This is an author acknowledgement, not enforced isolation or a declaration that the ref is trusted. It does not change checkout behavior, credentials, permissions, automatic PR checkout, or other diagnostics. The compiler does not infer data-only use from `working-directory`: commands can execute code outside that directory. Host tooling must not execute scripts, hooks, plugins, or configuration from the data checkout, including indirectly through validators or package managers. Keep tooling on a trusted ref and use separate, non-overlapping checkout paths.

The option defaults to `false` and accepts only literal booleans. If imports or repeated entries request the same checkout target, every merged request must set `data-only: true`; otherwise the warning remains enabled.

## PR Revision Binding

By default, the compiler-generated "Checkout PR branch" step fetches a specific commit SHA from the current repository's `origin`, then verifies the checked-out `HEAD` before reporting success or recording a patch baseline. It does not resolve a moving `refs/pull/N/head` during fetch.
Expand Down Expand Up @@ -114,6 +135,7 @@ checkout:
| `max-repos` | integer | Maximum unique repositories per `multi: true` checkout entry. Requires `allowed-repos` in multi mode; defaults to `10`. Must be a positive literal integer. Ignored in single-repository mode. |
| `allow-private-repos` | boolean | With `multi: true`, allow private/internal targets in a runtime list hosted by a private/internal repository. Requires `allowed-repos` in multi mode; defaults to `false` and must be a literal boolean. Public hosts always reject non-public multi targets, even when `true`. Ignored in single-repository mode. |
| `ref` | string | Branch, tag, or SHA to checkout. Defaults to the triggering ref. |
| `data-only` | boolean | Acknowledge data-only consumption by host steps and suppress only a separate checkout's checkout-ref warning. Defaults to `false`; literal boolean only. Does not suppress the default workspace checkout warning, enforce isolation, or change execution. All merged requests for the target must opt in. See [Separate Tooling and Data Checkouts](#separate-tooling-and-data-checkouts). |
| `path` | string | Path within `GITHUB_WORKSPACE` to place the checkout. Defaults to workspace root. |
| `github-token` | string | Token for authentication. Use `${{ secrets.MY_TOKEN }}` syntax. |
| `github-app` | object | GitHub App credentials (`client-id` or `app-id` (deprecated), `private-key`, optional `owner`, `repositories`). Mutually exclusive with `github-token`. `app` is a deprecated alias for the field name. Run `gh aw fix` to auto-migrate `app-id` to `client-id`. |
Expand Down
Loading
Loading