Text of github.github.com › gh-aw › specs › checkout-behavior-specification as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Checkout Behavior Specification | GitHub Agentic Workflows

Skip to main content Checkout Behavior Specification Version : 1.3.4 Status : Working Draft Publication Date : 2026-10-24 Editor : GitHub Agentic Workflows Team This Version : checkout-behavior-specification Latest Published Version : This document Abstract Section titled “Abstract” This specification defines normative checkout behavior in GitHub Agentic Workflows for activation, agent, and safe_outputs jobs. It specifies credential and token precedence, github-token and github-app resolution, trial mode behavior, side-repo targeting, sparse/shallow/fetch semantics, symlink handling during sparse activation checkout, submodule cleanup semantics, and checkout-manifest behavior used by safe output handlers.

Status of This Document Section titled “Status of This Document” This is a working draft and may change. It describes behavior mined from the current implementation in pkg/workflow/ and actions/setup/js/ . Table of Contents Section titled “Table of Contents” Introduction Conformance Checkout Model Authentication and Token Resolution Sparse, Shallow, Fetch, Symlink, and Submodule Behavior Trial Mode and Side-Repo Behavior Compliance Testing References Change Log 1.

Introduction Section titled “1. Introduction” 1.1 Purpose Section titled “1.1 Purpose” This document defines exactly how checkout is compiled and executed for: Activation job sparse checkouts Agent job checkouts safe_outputs job PR/push checkouts 1.2 Scope Section titled “1.2 Scope” This specification covers: checkout: parsing and merge behavior actions/checkout step generation Checkout credential persistence/cleanup behavior Token and GitHub App precedence across checkout and safe_outputs Sparse/shallow/fetch mechanics Symlink handling for activation sparse checkout Submodule credential cleanup behavior Trial mode and side-repo derivation behavior Checkout-manifest generation requirements for safe_outputs handler lookup 2.

Conformance Section titled “2. Conformance” 2.1 Requirements Notation Section titled “2.1 Requirements Notation” The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 . 2.2 Conformance Classes Section titled “2.2 Conformance Classes” C1 (Compiler conformance) : emits checkout YAML conforming to Sections 3–6.

C2 (Runtime conformance) : JS/sh handlers honor manifest safety, fetch behavior, and credential boundaries in Sections 4–6. 3. Checkout Model Section titled “3. Checkout Model” 3.1 Checkout Entry Parsing Section titled “3.1 Checkout Entry Parsing” checkout: MUST accept either a single object or an array of objects. Each entry MAY define: repository (or repo ), multi , allowed-repos , max-repos , allow-private-repos , ref , path , github-token (or legacy token ), github-app (or deprecated alias app ), safe-outputs-github-app , fetch-depth , fetch , sparse-checkout , submodules , lfs , current , wiki , and force-clean-git-credentials . github-token and github-app MUST be mutually exclusive per entry. safe-outputs-github-app applies only to safe_outputs git auth/token resolution.

It MUST NOT change agent/activation checkout authentication behavior. Runtime Repository Lists Section titled “Runtime Repository Lists” repo MUST be accepted as an alias for repository ; specifying both MUST fail. multi MUST be a literal boolean and MUST default to false. Only multi: true MUST enable repository-list expansion and the multi-repo restrictions in this subsection. Neither an expression selector nor allowed-repos alone MUST implicitly enable multi mode.

Without multi mode, an explicit repository or repo MUST resolve to exactly one owner/repo slug; empty, malformed, wildcard, and multiple resolved slugs (including duplicates) MUST fail before checkout. Literal lists MUST fail compilation. Runtime expression values MUST be validated as data before actions/checkout in both agent and safe-output jobs. Single-repository expressions MUST NOT require an allowlist, a non-root path prefix, visibility preflight, private-target opt-in, or explicit App scoping.

Normal single-checkout LFS, submodule, current , and wiki support MUST remain available. Multi-only policy fields MUST NOT activate or constrain a single checkout; their declared types still apply. repository and repo MUST select explicit repository names, not wildcard patterns. Literal repository wildcards MUST fail at compile time, and wildcard values in expression-resolved lists MUST fail at runtime. Wildcards MUST only be used in allowed-repos ; the allowlist MUST NOT discover or select repositories.

An entry with multi: true MUST expand its repository value as newline-separated owner/repo slugs at runtime. List expansion MUST require a non-empty allowlist and a literal, non-root path prefix. Each repository MUST be checked out under <prefix>/<owner>/<repo> . Matching and deduplication MUST be case-insensitive. Scoped wildcard patterns such as owner/* or */repo MAY be used. Unrestricted patterns such as * or */* MUST be rejected at compile time for literal values and at runtime for expression-resolved values.

An empty selected list MUST NOT select every allowed repository. allowed-repos expressions MUST be standalone references to trusted repository or organization variables. Caller-controlled inputs, step/job outputs, computed expressions, and expressions embedded in literal text MUST fail compilation. max-repos MUST be a positive literal integer no greater than 9007199254740991 and MUST require allowed-repos . Each runtime entry MUST default to a limit of 10 unique selected slugs after case-insensitive deduplication.

Oversized lists MUST fail in full before metadata requests or checkout action generation, not truncate. Agent and safe_outputs jobs MUST enforce the same limit. Separate runtime entries MAY have independent limits. Before checkout, the runtime MUST verify every selected repository against the allowlist and GitHub API metadata. Redirected canonical names MUST be checked again. A disallowed repository MUST fail the checkout job before creating any selected checkout and MUST be included in the agent failure issue according to the workflow’s failure-reporting settings, including safe-output checkout failures.

Runtime lists MUST reject private/internal targets by default. An entry MAY explicitly opt in with the literal boolean allow-private-repos: true , which MUST require allowed-repos . Expressions and non-boolean values MUST fail compilation; malformed runtime flag values MUST fail before authenticated reads. The opt-in MUST permit non-public targets only on private/internal hosts. If the workflow repository is public, non-public targets MUST be rejected even when the flag is true, regardless of the checkout credential’s access.

Agent and safe_outputs jobs MUST enforce the same policy. Ordinary static checkout behavior MUST remain unchanged. Missing or unverifiable visibility MUST fail closed. Runtime lists MUST reject enabled submodules at compilation and runtime regardless of host visibility, because repository-controlled submodule URLs can bypass the repository allowlist. Generated dynamic checkout actions MUST disable submodules. Static checkout submodule support MUST remain unchanged.

Configured follow-up fetches MUST explicitly disable submodule recursion, even when local Git configuration enables it. Repository .gitmodules content MUST remain unchanged; generated checkout/finalization steps MUST NOT initialize it. Runtime lists MUST reject lfs: true at compilation and runtime regardless of host visibility, because repository-controlled LFS endpoints can bypass the repository allowlist. Generated dynamic checkout actions MUST disable LFS.

Existing target directories and symlinked path ancestors MUST be rejected. Runtime lists MUST NOT support current: true o

The rest of this page is on the live site.