actions/checkout：GitHub Action 用于检出仓库

actions/checkout（v7）是一个由 GitHub 官方维护的 TypeScript 语言实现的 GitHub Actions 核心工具。

这是什么

actions/checkout 用于将 Git 仓库检出到 $GITHUB_WORKSPACE 路径下，使后续步骤可以直接访问代码。它支持从 GitHub、GitHub Enterprise Server 或自定义 Git 实例克隆仓库，并自动处理身份验证和清理。

官方仓库地址为 https://github.com/actions/checkout，最新版本为 v7.0.0（2026 年 6 月发布）。

解决的问题

1. fork PR 触发时的安全漏洞：pull_request_target 和 workflow_run 触发器默认使用 base 仓库的 GITHUB_TOKEN，若直接检出 fork 代码（恶意仓库），可能触发「pwn request」攻击。v7 版本默认拒绝检出 fork PR 代码，必须显式开启 allow-unsafe-pr-checkout: true。
2. 凭据持久化安全问题：早期版本将 token/SSH 密钥直接写入 .git/config，v6 已改存 $RUNNER_TEMP，v7 继续沿用此改进，避免 Docker 容器动作等场景的泄露风险。
3. Node.js 版本与依赖兼容性：v5 迁移至 Node 24 运行时，v7 进一步迁移至 ESM 模块，支持最新 @actions/* 包并修复已知安全漏洞。
4. Git 版本兼容性：当系统 Git < 2.18 时自动 fallback 到 REST API 拉取，避免老旧 Git 的下载限制。

核心功能

• 基础检出：默认只拉取触发事件的单一 commit（fetch-depth: 1），通过 ref、repository、path 自定义目标。
• 进阶选项：
  • fetch-depth: 0：完整历史（所有分支、标签）。
  • sparse-checkout + sparse-checkout-cone-mode：仅检出指定文件夹（如 .github、src），支持 cone-mode 优化。
  • filter、submodules、lfs：稀疏检出、子模块、Git LFS 文件下载。
  • persist-credentials：默认开启，自动将 token 写入本地 Git 配置（v6+ 改存临时目录）。
• SSH 支持：ssh-key、ssh-known-hosts、ssh-strict、ssh-user，支持 GitHub Enterprise Server 等私有实例。
• 多仓库处理：通过嵌套或 side-by-side 方式检出多个仓库（官方场景示例）。
• 自动清理：post-job 步骤移除 token 和 SSH 密钥，set-safe-directory: true 默认启用。
• Git fallback：Git 未在 PATH 中时自动降级 REST API。
• Node 24 运行时：v7 要求 Actions Runner v2.327.1+。

亮点 / 与同类相比

• v7 最大亮点：默认拒绝检出 pull_request_target/workflow_run 的 fork PR 代码，彻底解决「pwn request」漏洞（GitHub 官方博客 2026 年 6 月 18 日宣布）。需使用 allow-unsafe-pr-checkout: true 后才能启用，需自行评估风险。
• v6 改进：凭据存储从 .git/config 改为 $RUNNER_TEMP，兼容 Docker 容器动作（Runner v2.329.0+）。
• v5 改进：切换 Node 24 运行时，性能提升。
• v4 以来持续改进：支持 sparse-checkout、cone-mode、multi-repo 检出、SSH 企业实例；默认只拉 1 个 commit，安全且高效。
• 与竞品对比：相比社区 fork（如 taiki-e/checkout-action），官方版依赖更新更及时、安全审计更严格；相比其他第三方 Action，GitHub 官方维护 + 完整文档 + 推荐权限示例。
• 安全与维护：GitHub 明确不再接收新贡献，推荐通过 Community Discussions 或官方支持报告高优先 bug，security issue 按 security.md 处理，仍提供安全更新和重大 breaking change 修复。

适合谁用 / 上手

• 适合：所有使用 GitHub Actions 的开发者，特别推荐在依赖 pull_request_target 的工作流中升级到 v7（直接提升安全）；需要稀疏检出、完整历史、SSH 企业实例、Docker 容器动作、或多仓库并行检出的团队；需要 Node 24 运行时兼容的项目。
• 不适合：极少数极高安全敏感场景下仍需手动 fork 且评估过风险的项目（需显式开启参数）；已迁移到其他自托管 runner 且不依赖官方 token 的环境。
• 上手步骤（零配置即可）：
  1. 在 workflow 文件中添加 - uses: actions/checkout@v7（推荐 pin major 版本）。
  2. 根据需求调整 with: 参数，例如：

     - uses: actions/checkout@v7
       with:
         fetch-depth: 0  # 完整历史
         sparse-checkout: |
           .github
           src
     

  3. 使用 ref 切换分支/标签/SHA，repository 切换其他仓库。
  4. 认证：默认使用 GITHUB_TOKEN，若需 PAT/SSH，分别设置 token、ssh-key。
  5. 验证：git 命令、ls $GITHUB_WORKSPACE 正常运行，git push 等认证操作无缝工作。
• 推荐权限：参考官方文档，遵循 least-privilege 原则（Read 即可）。
• 迁移提示：v6+ 无需修改 workflow 代码，git fetch/push 自动工作；v7 新增安全参数，升级后无需额外修改。

参考官方仓库 README 和 release notes（https://github.com/actions/checkout/releases），即可快速上手并利用 v7 的安全增强。