用途:在审查或编写 gh-aw 中针对仓库检出执行 git、gh 或其他远程操作的代码时使用,覆盖 pkg/workflow/、actions/setup/js/ 以及编译后的 .lock.yml 工作流。
背景:工作流 checkout: 块中每个条目可声明自己的凭据(github-token:、github-app:),编译器会将其接入对应的 actions/checkout 步骤(pkg/workflow/checkout_step_generator.go)。生成的检出始终设置 persist-credentials: false,步骤结束后磁盘上的仓库不保留凭据,克隆期间仅使用 actions/checkout 内部令牌,并在 post-step 中清除。后续步骤若需认证,必须重新在命令级注入令牌(如 git -c http.extraheader=...),或通过 env 传入每个检出的令牌;编译器不会自动把每个检出的 github-token 传递到下游步骤。
两类上下文刻意不携带 git 凭据:safe-outputs MCP 服务器及其处理器(generate_git_bundle.cjs、generate_git_patch.cjs、create_pull_request.cjs),其错误明确提示无私有仓库凭据,fetch/push 会失败;以及 actions/checkout 之后的 agent 运行时,其提示明确要求不要尝试 git fetch、pull、push 等认证操作,应报告分支不可用而非尝试获取。
审查清单:判断是否触及远程,本地命令(symbolic-ref、rev-parse、log、show、merge-base、diff、status)无需凭据,而 fetch、pull、push、clone、ls-remote、remote(set-url/add/update)及部分克隆的按需 blob 获取需要;确认操作的是哪个检出,跨仓库条目应使用该条目的 github-token 而非默认 GITHUB_TOKEN,并确认令牌已传入步骤 env,否则应拒绝远程操作并优雅降级;确认由哪个作业/上下文发出,agent 作业与 safe-outputs MCP 服务器均无 git 凭据,远程操作须用 try/catch 包裹、软失败并给出明确的“无凭据”错误;注意稀疏/浅/单体仓库问题,避免加深(git fetch --unshallow、--deepen=N)或加宽(git fetch origin '+refs/heads/*')检出,应在编译期通过 fetch:、fetch-depth:、sparse-checkout: 扩展;gh 是 REST 而非 git,gh api 使用步骤 env 中的 GH_TOKEN,不会自动继承每个检出的 PAT,跨组织私有仓库需传入正确令牌或接受 404 并处理。
相关文档:docs/src/content/docs/reference/checkout.md、docs/sparseness.md、pkg/workflow/checkout_step_generator.go、actions/setup/md/safe_outputs_push_to_pr_branch.md。