GitHub Repository Checkout | GitHub Agentic Workflows
Skip to main content GitHub Repository Checkout The checkout: frontmatter field controls how actions/checkout runs in the agent job. Use it to change checkout settings, check out multiple repositories, or disable checkout entirely. By default, the agent checks out the workflow’s repository with a shallow fetch ( fetch-depth: 1 ). On pull_request events it also checks out the PR’s selected commit (see PR Revision Binding ).
On pull_request_target events, automatic PR checkout is disabled by default , and pull-request-floating-head does not enable it. Most workflows need no checkout: configuration. Activation separately checks out workflow configuration to load runtime imports and skills. On pull_request , pull_request_review , and pull_request_review_comment events, this sparse checkout uses the PR base SHA . On other events it uses the normal activation ref. checkout: options do not override this activation checkout.
For reusable workflow_call workflows, it uses the resolved callee SHA when no PR event is active, and skips cross-repository checkout if authentication may fall back to the caller’s GITHUB_TOKEN . Use checkout: to check out additional branches or repositories, or set checkout: false for workflows that access code only through GitHub tools. Checkout and Host Step Order Section titled “Checkout and Host Step Order” The agent job runs these steps in order: Repository checkout, using checkout.ref when configured.
Imported steps: (including shared toolchain setup). The workflow’s own steps: . Automatic “Checkout PR branch”, when enabled for the event. pre-agent-steps: . The sandboxed engine. Keep the host workspace on a trusted ref. To inspect an untrusted ref, fetch it only as data. Do not check out an untrusted branch on the host or run its scripts: Git hooks and branch-controlled agent configuration can execute. For PR-head work, use automatic PR checkout, which restores the trusted agent configuration.
Disabling that checkout also disables the configuration restore. Separate Tooling and Data Checkouts Section titled “Separate Tooling and Data Checkouts” When trusted host tooling reads a separate checkout only as data, set data-only: true on that checkout to suppress its checkout-ref warning: 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 data-only is an author acknowledgement.
It does not enforce isolation, prove the ref is trusted, or change checkout behavior, credentials, permissions, or other diagnostics. The compiler does not infer data-only use from working-directory , because commands can run code outside that directory. Host tooling must not execute scripts, hooks, plugins, or configuration from the data checkout, including through validators or package managers. Use non-overlapping checkout paths.
The option defaults to false and accepts only literal booleans. If imports or repeated entries target the same checkout, every merged request must set data-only: true . PR Revision Binding Section titled “PR Revision Binding” By default, the “Checkout PR branch” step fetches a specific commit SHA from the repository’s origin . It then verifies the checked-out HEAD before reporting success or recording a patch baseline.
It never resolves a moving refs/pull/N/head during fetch. Trigger Selected revision by default Head movement pull_request , except labeled and unlabeled Event-recorded PR head SHA Retains the event revision, even if the branch moves or is deleted. pull_request label events Event-recorded PR head SHA Must match the live head before and after fetch. pull_request_review / pull_request_review_comment Review or review-comment commit_id Must match the live head before and after fetch.
Revision-bound workflow_dispatch Supplied aw_context.pr_head_sha Must match the live head before and after fetch. issue_comment , routed comment commands, or manual PR dispatch without revision evidence Current API head SHA Pins the selected head and rejects a change during fetch. Does not establish revision approval. These rules apply only to compiler-generated automatic PR checkout. The floating-head opt-in selects the current head instead.
Centralized command and label dispatch passes event-recorded revision evidence in aw_context.pr_head_sha . A revision-bound dispatch must supply a full 40-character SHA matching the current PR head. Missing evidence, malformed PR context, API failures, and detected head changes stop checkout. The job never continues on the previous workspace. Issue comments have no historical head SHA. Comment commands therefore authorize current-head execution , not approval of a specific revision.
They require valid comment and PR-update timestamps, warn if the PR changed after the comment, and pin and recheck the resolved head. Timestamps cannot prove which revision was reviewed, because unrelated activity also updates the PR. Workflows that require revision approval should use a revision-bearing PR or review event, or set checkout: { pull-request: false } . Do not rely on a comment command alone to approve privileged execution of PR code.
These checks keep the existing actor-permission floor and same-repository bot restrictions. A matching SHA proves commit identity, not that the PR code is safe to run with credentials. Fetching still needs credentials available to the checkout step. The helper does not persist credentials, widen sparse paths, or unshallow the repository. After successful checkout, the unified session records a workflow.pr_checkout_revision event with prNumber and the full, lowercase selectedSha .
Allow Floating Head Section titled “Allow Floating Head” To select the current PR head at execution time instead of the triggering event’s revision, opt in: checkout: pull-request-floating-head: true The value must be a literal boolean; strings and expressions are rejected. With true , checkout resolves the current head through the PR API and uses its commit count for fetch depth. It still fetches that specific SHA, rechecks the head after fetch, and verifies HEAD .
A head change during fetch fails. This option does not restore mutable-ref fetching. Actor permissions, fork and bot restrictions, dispatch validation, and safe-output lifecycle checks still apply. The setting applies workflow-wide when any checkout: entry enables it. It has no effect when checkout: false , pull-request: false , or the compiler’s PR-target policy suppresses the PR checkout. Recompile after changing it.
Custom Checkout Settings Section titled “Custom Checkout Settings” Override default settings such as fetch depth or authentication: checkout : fetch-depth : 0 # Full git history github-token : ${{ secrets.MY_TOKEN }} # Custom authentication Or use GitHub App authentication: checkout : fetch-depth : 0 github-app : client-id : ${{ vars.APP_ID }} private-key : ${{ secrets.APP_PRIVATE_KEY }} Check out additional repositories alongside the main one: checkout : - fetch-depth : 0 - repository : owner/other-repo path : ./libs/other ref : main github-token : ${{ secrets.CROSS_REPO_PAT }} Configuration Options Section titled “Configuration Options” Field Type Description pull-request boolean Set false to disable automatic PR checkout and its base-config snapshot/restore steps.
The normal repository checkout stays enabled. pull-request-floating-head boolean Select the current API head instead of event/review revision evidence. Defaults to false ; literal boolean only. Applies workflow-wide. See Allow Floating Head . repository string Explicit repository in owner/repo format, or a newline-separated list with multi: true . Without multi , expressions must resolve to exactly one repository and need no allowlist.
No wildcards. Defaults to the current repository. repo string Alias for repository ;
The rest of this page is on the live site.