docs: expand checkout: section in frontmatter reference

[Copilot]

The checkout: entry in the frontmatter reference was a stub — one example (checkout: false) and a redirect to the cross-repository page, leaving readers without inline guidance on the most common use cases.

Changes

• Subsections for each distinct usage pattern: disabling checkout, single-repo customization, multi-repo array checkout, fetching additional refs, and hub-and-spoke current: true
• Configuration options table covering all supported fields (repository, ref, path, github-token, github-app, fetch-depth, fetch, sparse-checkout, submodules, lfs, current) with types and descriptions
• Concrete examples for PAT and GitHub App auth, multi-repo arrays, and fetch: patterns

checkout:
  - fetch-depth: 0
  - repository: owner/other-repo
    path: ./libs/other
    ref: main
    github-token: ${{ secrets.CROSS_REPO_PAT }}

The link to Cross-Repository Operations is retained for merging behavior and advanced patterns.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

Expands the checkout: frontmatter reference from a stub into a more complete, inline guide for common actions/checkout usage patterns in agent jobs.

Changes:

• Adds structured subsections for disabling checkout, single-repo overrides, multi-repo checkouts, extra ref fetching, and selecting a primary repo (current: true).
• Introduces a configuration options table describing supported checkout: fields.
• Adds concrete YAML examples for PAT vs GitHub App auth, multi-repo arrays, and fetch: usage.

Comments suppressed due to low confidence (2)

docs/src/content/docs/reference/frontmatter.md:683

• current is validated as “only one logical checkout target” (unique repository+path after merging), so multiple entries that merge into the same target can still set current: true. The wording “Only one entry may set current: true” is slightly stricter than the actual behavior; consider rephrasing to match the logical-target constraint.

| `current` | boolean | Mark this checkout as the agent's primary working repository. Only one entry may set `current: true`. |

docs/src/content/docs/reference/frontmatter.md:681

• In the options table, fetch uses string \| string[] while submodules is written as string / bool and uses bool instead of boolean. For consistency and clarity, consider using the same union/type notation as the other rows (e.g., string \| boolean).

| `submodules` | string / bool | Submodule handling: `"recursive"`, `true`, or `false`. |

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The table claims to list all supported checkout: fields, but the implementation also accepts token as a backward-compatible alias for github-token (see parsing in pkg/workflow/checkout_manager.go around checkoutConfigFromMap). Consider adding a token row marked as deprecated/legacy, or mention the alias in the github-token row so readers aren’t surprised when they see token: used in existing workflows.

This issue also appears in the following locations of the same file:

• line 683
• line 681

Suggested change

	| `github-token` | string | Token for authentication (`${{ secrets.MY_TOKEN }}` syntax). |
	| `github-token` | string | Token for authentication (`${{ secrets.MY_TOKEN }}` syntax). Also accepts legacy alias `token` for backward compatibility. |