checkout：让 GitHub Actions 工作流取得仓库代码
一分钟看懂
checkout 是 GitHub 官方维护、也是 GitHub Actions 工作流中最常见的 Action 之一。它负责把指定仓库和代码版本检出到运行器的工作目录 $GITHUB_WORKSPACE，让后续步骤能够读取源代码、安装依赖、执行测试、构建产物或发布版本。
很多工作流把它放在第一个步骤。虽然功能看起来只是“拉取代码”，但它还处理分支、提交、身份凭据、浅克隆、子模块、Git LFS 和稀疏检出等细节。正确配置这些选项，能够在构建速度、历史完整性和安全性之间取得平衡。
你可以用它做什么
- 检出当前提交：让 CI 针对触发工作流的分支、标签或合并请求运行。
- 检出指定版本：通过
ref指定分支、标签或提交 SHA，用于对比、发布或回归测试。 - 取得完整历史：设置合适的
fetch-depth，让版本计算、变更日志或差异分析工具正常工作。 - 处理大型文件和子模块：按需启用 Git LFS 或拉取子模块。
- 只取仓库的一部分：使用稀疏检出减少大型单体仓库的下载量。
- 组合多个仓库：把主仓库、私有依赖仓库或工具仓库检出到不同目录。
主要能力
默认情况下，checkout 会围绕当前工作流对应的提交进行检出，并尽量减少不必要的传输。常见配置包括 ref、repository、path、token、fetch-depth、submodules、lfs 和 sparse-checkout。
需要注意的是，浅克隆适合普通编译测试，却可能让依赖 Git 历史的工具得不到正确结果。例如自动生成版本号、比较多个标签或制作完整变更日志时，通常需要把 fetch-depth 设为 0，以获取所有分支和标签。反过来，如果只是执行单次构建，保留浅克隆能节省时间和网络流量。
适合哪些人
几乎所有使用 GitHub Actions 并需要访问仓库内容的项目都会用到它，包括前后端构建、自动测试、容器镜像、文档发布和版本发布流程。只有完全不需要读取仓库代码的工作流，例如单纯调用远程接口，才可能省略。
怎么开始使用
在工作流的 steps 中加入官方 README 当前推荐的 actions/checkout 主版本，然后在后续步骤执行构建或测试命令。普通项目先使用默认参数即可；遇到版本信息缺失、找不到标签、子模块为空等问题时，再针对性调整 fetch-depth、submodules 或 lfs。
访问其他私有仓库时，默认的 GITHUB_TOKEN 可能没有相应权限，需要使用具有最小必要权限的 GitHub App Token 或个人访问令牌，并通过 Secrets 提供。不要把令牌直接写入工作流文件。
使用前需要知道
checkout 默认会把用于认证的令牌配置到本地 Git 环境，方便后续脚本执行经过认证的 Git 操作，并在任务结束阶段清理。如果后续步骤不需要推送或访问受限资源，可以设置 persist-credentials: false，减少不受信任脚本接触凭据的机会。
工作流应遵循最小权限原则，普通读取场景通常只需要 contents: read。处理来自 Fork 的拉取请求时，不要让未经审查的代码接触高权限密钥。对安全要求很高的环境，除了使用可信的官方 Action，还可以按完整提交 SHA 固定依赖版本，避免可移动标签变化带来供应链风险。
此外，检出多个仓库、递归子模块或完整历史会显著增加下载量和执行时间。应根据后续步骤的真实需要开启，而不是把所有选项一次性打开。