如果你在 GitHub Actions 的流水线里写过git checkout main却撞上fatal: not a git repository这种报错大概率不是你的 Git 命令写错了而是把本地开发命令和 CI 环境里的代码获取步骤搞混了。这个场景在刚开始接触 GitHub Actions 的团队里非常常见甚至很多有经验的开发者也会因为一时惯性踩进去。本文要重点讲清楚的是actions/checkout它是什么样的工具和git checkout、git clone有什么区别核心参数怎么配置以及一条从零到可运行的完整 CI 工作流应该怎么写。更重要的是我会把“为什么在 GitHub Actions 里不要直接写git checkout”说透让你以后再遇到类似问题能直接判断出问题出在认证、仓库路径、ref 还是工作目录而不是靠猜。读完这篇文章你会得到三个明确结论第一CI 拉取代码这件事默认就应该交给actions/checkout第二actions/checkout的参数决定了代码版本、子模块、LFS 和认证行为每个都值得理解第三遇到常见的 checkout 报错你可以按照一套固定的排查顺序快速定位。建议先把文章收藏后面写流水线时对照着用。1. 这篇文章真正要解决的问题先还原一个非常典型的现场。某天你往仓库里推送了一个新提交然后在 GitHub Actions 里新建了一个 workflow写了一个步骤steps: - name: Checkout run: git checkout main你期待它像本地一样切到 main 分支然后开始构建。但实际运行结果却五花八门最常见的是fatal: not a git repository (or any of the parent directories): .git也有可能是fatal: could not read Username for https://github.com。有些同学排错半天最后发现 runner 环境里连一个.git目录都没有这才意识到 CI 机不是自己的电脑。GitHub Actions 的 runner 每次执行 job 时都会准备一个干净的工作环境。你可以把它理解成一台临时分配的虚拟机默认工作目录通常是/home/runner/work/仓库名/仓库名这个目录一开始是空的。你没有本地终端里那些已经配置好的 SSH key、git config、远程地址和登录凭据。所以在这个环境里直接写git checkout本质上是“在一个没有仓库对象的环境里执行 Git 子命令”自然无法成功。因此这篇文章首先要解决的问题就是消除“本地 Git 操作可以照搬到 CI”这个惯性误区。CI 环境里获取代码不是单纯的一个git clone或者git checkout它需要处理认证、目标提交、历史深度、子模块、LFS 等多个环节。而actions/checkout正是把这些环节封装成标准步骤的官方 action。读完第一节你应该建立第一个判断只要你在 GitHub Actions 的 workflow 里需要把代码取到 runner 工作区第一选择永远是actions/checkout而不是手动拼装 Git 命令。后续的所有参数和排错都建立在这样一个前提上。2. actions/checkout 与 git checkout概念辨析与选择逻辑2.1 两个不同层级的概念git checkout是 Git 自带的一个子命令。它做的事情主要有两类一是切换分支二是恢复工作区中的文件到某个提交版本。它改变的是本地仓库当前工作区的状态、HEAD 指针和索引状态。在本地开发中几乎每天都会用到但它依赖的前提是你当前已经在一个完整的 Git 仓库中并且本机有相应的认证凭据。actions/checkout则完全不同。它不是命令行工具而是 GitHub 提供的一个 Action 组件在 workflow 的 YAML 里通过uses: actions/checkoutv4这类语法引用。它本身是一段被封装好的逻辑内部会调用 Git 相关命令但对外暴露的是 action 参数。它解决的是“在一台全新的 runner 上如何安全、标准地拿到指定仓库的指定提交”这个任务。很多人在网上搜索git checkout problem时其实遇到了多种不同的问题。有人是本地切换分支不干净有人是 CI 中拉不到代码还有人是在 workflow 里写了 Git 命令但认证失败。这些问题看起来都带“checkout”关键词根因却不在同一个层级。先把概念区分开后面排错才不会把锅乱扣到某个工具上。2.2 为什么 workflow 里不能直接依赖 git clone 或裸的 git checkout从直觉上看git clone也可以拉代码而且似乎更简单。但放到 GitHub Actions 环境中直接使用裸git clone会面临几个实际问题。首先是认证。runner 上没有你的个人访问令牌也没有 SSH 私钥。即使仓库是公开的你也要能拼出正确的 URL如果是私有仓库裸命令大概率会直接要求输入用户名密码而 CI 环境里不会有人工交互。actions/checkout会自动使用 GitHub 提供的GITHUB_TOKEN把认证信息注入到 Git 命令中所以表面看起来“不用认证”就成功了。其次是版本一致性问题。GitHub Actions 的触发事件通常会带一个具体的提交 SHA比如 push 事件里有github.shapull_request 事件里有源分支最新的提交。actions/checkout默认会检出触发这个 workflow 的那个提交确保 CI 构建的代码和触发时刻保存一致。而直接git clone默认拿到的是默认分支的最新 HEAD两者可能完全不同。你在本地修复了一个 bug推上去之后 CI 却还在用旧代码这种情况往往就是这么来的。2.3 选择逻辑什么时候用哪个对比维度git checkoutgit cloneactions/checkout运行位置本地终端任意有 Git 的环境GitHub Actions runner主要目标切换分支 / 恢复文件克隆仓库获取指定提交到工作区认证支持依赖本机凭据依赖本机凭据自动注入 GITHUB_TOKEN默认提交当前分支 HEAD默认分支 HEAD触发本次 workflow 的提交子模块默认不递归默认不递归参数submodules可控制Git LFS默认不拉取默认不拉取参数lfs可控制推荐场景日常本地开发手动复制仓库GitHub Actions 工作流所以选择的逻辑其实非常简单在 GitHub Actions 的 YAML 里凡是需要“拉取代码到 runner 工作区”的步骤都使用actions/checkout至于git checkout可以在actions/checkout执行完之后作为后续 run 步骤中的一条命令来操作本地已经存在的仓库对象。也就是说两者不是非此即彼的替代关系而是不同生命周期阶段的不同工具。先有仓库才能谈得上git checkout切换分支。3. actions/checkout 的核心参数与运行机制3.1 常用参数actions/checkout的参数并不复杂但每个参数在真实项目中都有其存在的必要性。下面这份 YAML 展示了最常用的配置组合- name: Checkout uses: actions/checkoutv4 with: repository: your/repo ref: main token: ${{ secrets.GITHUB_TOKEN }} fetch-depth: 0 persist-credentials: true path: . submodules: recursive lfs: true clean: true接下来逐一拆解这些参数。repository参数用于指定要拉取的仓库默认是当前 workflow 所在的仓库格式通常是owner/repo。这个参数的存在意味着你可以在一个仓库的 workflow 中拉取另一个仓库的代码。这在文档仓库构建、多仓库联调、微服务批量构建等场景中非常有用。不过要注意跨仓库拉取私有仓库时必须提供一个对目标仓库有读取权限的 token。ref参数的作用是决定检出哪个 Git 引用可以是分支名、tag 或 commit SHA。默认情况下它使用触发 workflow 的那个 ref例如refs/heads/main或refs/tags/v1.0.0。这里最容易踩的坑是如果在 workflow 里写死了ref: develop那么后续每次执行都会拉取 develop 分支的最新提交而不是触发 workflow 的那个提交。对于需要精确复现的 CI 场景如果不确定该写什么优先使用默认值。token参数默认使用${{ secrets.GITHUB_TOKEN }}。GITHUB_TOKEN是 GitHub 自动创建的临时访问令牌会自动过期并且权限可以在仓库设置中控制。对于大多数仓库而言这个默认 token 已经有读取当前仓库代码的权限。如果 workflow 需要访问其他私有仓库就需要结合repository参数并提供更高权限的 PATPersonal Access Token。fetch-depth控制 Git 克隆的深度。默认值是 1也就是浅克隆只拉取最近一个提交。这样最快、占用磁盘最少适用于大多数构建任务。当你需要统计提交记录、计算差异文件、或者执行某些需要完整历史的 Git 操作时可以设置为 0表示拉取完整历史。设置成比如3则只拉取最近 3 个提交这是一种兼顾速度与信息量的折中方案。persist-credentials默认是true意味着 token 会被持久化到 runner 的 Git 配置中使得后续步骤执行git push等命令时不需要重新认证。如果你的 workflow 后续没有推送需求建议显式设置为false。这能减少 token 暴露在多个步骤中的风险尤其在自托管 runner 上安全性更重要。path指定代码存放的相对路径默认是当前工作目录。这个参数非常实用。当 workflow 需要同时拉取当前仓库和另一个仓库时可以用path: repo-a、path: repo-b把它们隔离到不同目录避免互相覆盖。submodules用于控制是否递归拉取子模块。可选值通常有true、recursive等。如果项目使用 Git Submodule但没有配置这个参数你会看到子模块目录存在却为空进而引发编译资源缺失、静态文件找不到等连锁问题。处理嵌套子模块时使用recursive会比较稳妥。lfs参数用于控制是否下载 Git LFS 大文件。如果项目用 Git LFS 管理二进制资源构建时又依赖这些文件需要设置为true。不设置的话Git LFS 文件可能只保留一个文本指针真正的文件内容不会出现在工作区。clean参数默认是true表示检出前清理工作目录中的残留文件。自托管 runner 环境下上一次构建可能留下大量文件如果不清理很容易造成“本地能过、CI 不能过”的假性失败。保持默认值通常是最安全的选择。3.2 运行机制它本质上做了什么理解actions/checkout的运行机制对排错非常有帮助。它在执行时大致会做这几件事根据repository和token构造带认证信息的远程地址。根据fetch-depth执行对应的 fetch 操作决定拉取的历史深度。根据ref切换到对应的提交并把工作区文件恢复出来。根据submodules和lfs决定是否拉取子模块和大文件。最后根据clean和path等参数调整工作区状态。这也是为什么你能在日志里看到Syncing repository、Checking out the ref、HEAD is now at这类关键字。看到这些输出说明 checkout 正在正常执行如果在这一步报错问题往往出在认证、仓库路径或 ref 名称而不是后面的构建命令。4. 环境准备与前置条件让 GitHub Actions 先跑起来4.1 账号和权限准备要使用actions/checkout首先需要一个 GitHub 账号和一个启用了 Actions 的仓库。公开仓库开箱即用你不需要额外配置GITHUB_TOKEN默认就有读取代码的权限。对于私有仓库需要确认仓库的 Actions 功能是开启状态并且默认的GITHUB_TOKEN权限设置正确。在仓库的Settings - Actions - General下可以设置 Workflow 的权限。这里有“Read repository contents permission”只读和“Read and write permissions”读写两种主要选项。如果只是让actions/checkout拉代码只读就足够了。如果你后续需要在 workflow 中创建 tag、推送提交那就需要开启读写权限但要注意这也会扩大 token 的暴露范围。如果 workflow 需要访问另一个私有仓库建议在Settings - Secrets and variables - Actions中创建一个 secret把具有repo权限的 PAT 放进去。不要在 YAML 里直接写 token这是最基本的底线。secret 在 GitHub 的网页界面中是隐藏的只有进入对应 job 运行时才会注入环境变量因此在日志中不会被直接看到。4.2 workflow 目录结构GitHub Actions 的工作流文件必须放在.github/workflows/目录下文件后缀是.yml或.yaml。一个典型项目目录如下my-project/ ├── .github/ │ └── workflows/ │ └── ci.yml ├── src/ │ └── ... └── package.json没有这个目录就手动创建文件命名没有硬性要求但建议使用有意义的名称比如ci.yml、build.yml、deploy.yml。工作流文件并不是推一次就能修改一次每次 push 到仓库后GitHub 都会重新解析 YAML所以如果你改了配置却发现 Actions 没有响应先看看是否真的推到了默认分支。4.3 runner 环境与 Git 版本GitHub 托管的 runner 预装了 Git操作系统镜像会保持 Git 版本更新到较新的程度大多数情况下你不需要手动安装。如果你使用自托管 runner需要自行保证 Git 版本足够新并检查 runner 工作目录的权限。自托管 runner 和官方 runner 的行为差异比较大尤其是在文件清理、环境变量和用户权限方面。在编写 workflow 时建议不要依赖当前 runner 的默认环境变量来做目录拼接。最稳妥的方式是在步骤中使用 GitHub Actions 提供的上下文例如${{ github.workspace }}它代表 checkout 之后工作目录的绝对路径。用这个变量引用代码路径比硬编码/home/runner/work要可靠得多。5. 完整示例从零编写可用的 CI 工作流5.1 最小示例拉取代码并运行测试下面是一份结合 Node.js 项目的最小 CI 示例。我会在注释里标明关键作用方便你直接复制到项目中改造成自己的流程# 文件路径.github/workflows/ci.yml name: CI on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: test: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 20 cache: npm - name: Install dependencies run: npm ci - name: Run tests run: npm test这段配置的含义是只要 main 或 develop 分支收到 push或者有人向 main 发起 pull_request就触发test这个 job。job 运行在ubuntu-latest上。Checkout code步骤会把当前仓库的代码拉到 work 目录后面的Setup Node.js安装 Node.js 20 并启用 npm 缓存npm ci根据锁文件安装依赖最后npm test执行测试。这里最核心的一步就是uses: actions/checkoutv4。如果没有这一步后面的npm ci找不到package.jsonnpm test也找不到src目录你会看到一堆No such file or directory的报错。所以对于大多数项目checkout 都应当是 job 中最早的关键前置步骤。另外本文里的actions/checkoutv4是一个常用 tag实际使用时建议到actions/checkout仓库查看当前维护状态选择稳定的版本。教程的重点是通用思路版本 tag 可以按项目实际情况调整。5.2 高级示例拉取多个仓库并使用不同目录现实项目里经常出现“一个 CI 流程需要同时拉取主代码和另一个私有基础库”的需求。下面的示例展示了如何用path和repository参数完成多仓库协作# 文件路径.github/workflows/multi-repo.yml name: Multi Repo Build on: workflow_dispatch: jobs: build: runs-on: ubuntu-latest steps: - name: Checkout main repo uses: actions/checkoutv4 with: path: main-repo - name: Checkout docs repo uses: actions/checkoutv4 with: repository: my-org/my-docs token: ${{ secrets.DOCS_REPO_TOKEN }} path: docs-repo - name: Show directories run: | ls -la main-repo ls -la docs-repo这里需要注意几个关键点。第一个Checkout main repo使用的是当前仓库path: main-repo会把代码放到工作目录下的main-repo子目录。第二个Checkout docs repo拉取的是my-org/my-docs仓库并且通过token: ${{ secrets.DOCS_REPO_TOKEN }}传入一个有权限的 PAT。如果你不提供 token即使仓库存在私有仓库也无法访问。将多个仓库放到不同目录可以避免文件覆盖也让后续步骤能清楚地引用各自的代码路径。如果你需要的是“把多个仓库合并进同一个目录”那是另一个复杂问题actions/checkout 的path参数并不适合因为每个 action 会独立执行 clean 和 checkout容易互相覆盖。5.3 高级示例完整历史、子模块与 LFS下面是一个面向复杂仓库的配置适合需要完整历史、子模块和 Git LFS 的项目# 文件路径.github/workflows/full-checkout.yml name: Full Checkout on: pull_request: jobs: build: runs-on: ubuntu-latest steps: - name: Checkout with full history uses: actions/checkoutv4 with: ref: ${{ github.event.pull_request.head.sha }} fetch-depth: 0 submodules: recursive lfs: true token: ${{ secrets.GITHUB_TOKEN }}这段配置的逻辑是每当有 pull_request 事件时检出 PR 来源分支的最新提交 SHA。fetch-depth: 0拉取完整历史适合需要做代码差异分析、代码覆盖率增量、lint 差异对比等任务。submodules: recursive递归拉取子模块lfs: true在构建前下载 Git LFS 大文件。如果在使用这个配置后子模块目录仍然是空的优先检查你的仓库是否真的包含.gitmodules文件以及子模块地址是否是 runner 能访问的地址。LFS 文件没有下载时通常表现为文件内容是一段大小很小的文本指针而不是真实的二进制内容看到这种迹象就应当回头检查lfs参数。5.4 一个 Java/Maven 项目的对照参考如果你用的是 Java下面这个示例也可以对照使用# 文件路径.github/workflows/maven-ci.yml name: Maven CI on: push: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv4 - name: Set up JDK 17 uses: actions/setup-javav4 with: distribution: temurin java-version: 17 cache: maven - name: Build with Maven run: mvn -B package --no-transfer-progress这个示例说明的核心事实是无论项目技术栈是什么checkout 的思路完全一致。先取代码再搭工具链再构建最后测试或打包。唯一需要替换的是后续步骤里的工具链安装命令和构建命令。6. 运行验证与关键日志解读6.1 如何触发和查看运行结果将 YAML 文件推送到仓库后进入仓库的Actions标签页你会看到对应的工作流名称。点击工作流名称再点击具体的运行记录可以看到每个 job 的每个步骤列表。一个成功的Checkout code步骤通常会在展开后看到类似下面的日志片段Syncing repository: your-name/your-repo Git commit message: fix: update ci config ... HEAD is now at 7a3f5a2 fix: update ci configHEAD is now at ...这一行是最明确的成功信号。它表示 checkout 已经将工作区切换到了某个具体的 commit SHA。看到这行日志说明actions/checkout的主要使命已经完成。6.2 判断成功与失败的维度成功的标志不只是“job 是绿色”。你需要检查两件事第一Checkout code步骤本身是否通过第二Checkout code之后的步骤能否读到项目文件。如果 job 失败在Run tests说明 checkout 阶段是好的问题在依赖安装或命令本身如果失败点就是Checkout code那就要优先排查认证、仓库地址和 ref。6.3 常见日志特征速查Could not find ref developref参数写错了或目标分支不存在。Authentication failedtoken 无效或权限不足。fatal: unable to access ... 403私有仓库访问权限范围不够。Warning: submodule ... couldnt be found子模块地址或 token 权限有问题。LFS files not found没有开启lfs: true或者 LFS 文件尚未上传到远端。7. 常见问题与排查方法下面的表格汇总了我见过的高频场景。你可以把它当作一份排错清单遇到问题时逐行对照。问题现象可能原因排查方式解决方案fatal: not a git repositoryrunner 上没有仓库却在 run 里直接执行 git 命令检查步骤顺序和工作目录在步骤开头加入actions/checkoutfatal: could not read Username没有使用actions/checkout或persist-credentials被错误关闭检查是否手动执行 git clone/pull改用actions/checkout确认 token 参数remote: Repository not found.私有仓库 token 权限不足用 token 在本地测试git ls-remote使用有repo权限的 PATError: Input required and not supplied: token拉取非当前仓库时没有显式传 token检查repository参数和目标仓库访问权限为 secret 添加 tokenworkflow 总是拿到旧代码ref写死成某个分支或fetch-depth配置不当查看Checkout code日志中的 commit SHA使用默认ref或按需设置深度子模块目录为空没有配置submodules参数检查仓库是否有.gitmodules设置submodules: recursiveLFS 文件缺失没有配置lfs: true检查文件是否为 LFS 指针设置lfs: true后续步骤找不到代码文件checkout 放在了错误位置或path配置不对执行ls查看工作目录调整步骤顺序和path参数除了表格里的情况还有一个很隐蔽的问题需要单独强调actions/checkout默认会清理工作目录。如果你使用自托管 runner并且在同一台机器上并行跑多个 job可能会出现文件互相覆盖。遇到这种情况不要只在 workflow 层面加clean: false 更稳妥的做法是给每个 job 配置独立的临时目录或者使用官方托管的 runner。另一个常见误解是“在 workflow 里执行git checkout branch后后续步骤就能基于那个分支构建”。实际上actions/checkout已经处于 detached HEAD 状态它指向的是某个具体的 commit SHA而不是“符号分支”。如果你真的需要在 CI 中临时切换分支首先确认actions/checkout已经把仓库拉下来了然后在 run 中执行git checkout some-branch才是合理的操作。否则你会看到很多“branch not found”或“detached HEAD”提示。8. 最佳实践与工程建议8.1 让 checkout 尽量靠前我建议把actions/checkout放在每个 job 的前部。原因很简单后面的所有步骤几乎都依赖代码存量。虽然像actions/setup-node、actions/setup-java这类工具不依赖代码目录把工具链放在 checkout 之前也不是绝对不行但为了避免搞混工作目录统一保持“先 checkout再 setup再执行构建”的顺序团队成员理解起来更容易排查问题时也更省心。8.2 默认浅克隆按需加深fetch-depth: 1是大多数 CI 流程的最佳默认值。浅克隆不仅快而且不会把仓库历史全部拉到 runner 上减少带宽和磁盘消耗。只有在确实需要比较多个提交、计算改动文件、生成覆盖率增量报告时才需要提升深度。如果只想获取最近几条提交可以用具体的数字比如fetch-depth: 5。不要盲目把fetch-depth: 0写进所有 workflow除非你有明确需求。8.3 控制 token 暴露面GITHUB_TOKEN是自动生成、自动过期的这比手动创建 PAT 更安全。但在需要跨仓库访问时PAT 不可避免。使用 PAT 的时候请记住三个原则只能通过 GitHub Secrets 注入不要硬编码。尽量限制 PAT 的仓库范围和权限 scope。定期轮换并且把使用情况纳入组织审计。persist-credentials也要有意识地控制。如果构建过程不需要git push、不需要发布 tag建议设置persist-credentials: false。这样后续步骤不会继承无关的认证信息。相反如果部署步骤需要把构建产物提交回仓库就保持为true或单独提供一个有写权限的 token。8.4 结合缓存提升效率actions/checkout只负责代码获取不负责依赖缓存。对于依赖安装比较重的项目建议结合actions/setup-node、actions/setup-java和actions/cache做依赖缓存。典型的执行顺序是checkout - setup 工具链 - 恢复缓存 - 安装依赖 - 构建测试。缓存能显著缩短 workflow 执行时间尤其是在大型 Spring Boot 服务或前端 monorepo 项目中。要注意的是不要试图用 cache action 缓存 checkout 生成的.git目录。Git 仓库的完整性和版本一致性比缓存收益重要得多缓存.git可能导致不同 commit 之间状态混乱反而引入更难排查的问题。8.5 自托管 runner 的清理策略自托管 runner 不会像官方 runner 那样每次 job 结束后自动清理。建议在 workflow 中显式设置clean: true并在关键步骤里使用固定工作目录。更稳妥的做法是使用官方 runner 或者定期清理 runner 上的 Python/Gradle/npm 缓存目录。如果多个 workflow 共用同一台 runner还要考虑并发时的目录隔离避免不同分支构建互相影响。8.6 分支保护与权限的配合分支保护规则和 Actions 权限是两个独立但互相影响的概念。如果仓库启用了分支保护那么来自pull_request事件的 workflow 拿到的GITHUB_TOKEN默认是只读的不能向受保护分支推送代码。如果你需要“验证通过后自动合并”或“自动更新依赖 PR”通常
如果你在 GitHub Actions 的流水线里写过git checkout main却撞上fatal: not a git repository这种报错大概率不是你的 Git 命令写错了而是把本地开发命令和 CI 环境里的代码获取步骤搞混了。这个场景在刚开始接触 GitHub Actions 的团队里非常常见甚至很多有经验的开发者也会因为一时惯性踩进去。本文要重点讲清楚的是actions/checkout它是什么样的工具和git checkout、git clone有什么区别核心参数怎么配置以及一条从零到可运行的完整 CI 工作流应该怎么写。更重要的是我会把“为什么在 GitHub Actions 里不要直接写git checkout”说透让你以后再遇到类似问题能直接判断出问题出在认证、仓库路径、ref 还是工作目录而不是靠猜。读完这篇文章你会得到三个明确结论第一CI 拉取代码这件事默认就应该交给actions/checkout第二actions/checkout的参数决定了代码版本、子模块、LFS 和认证行为每个都值得理解第三遇到常见的 checkout 报错你可以按照一套固定的排查顺序快速定位。建议先把文章收藏后面写流水线时对照着用。1. 这篇文章真正要解决的问题先还原一个非常典型的现场。某天你往仓库里推送了一个新提交然后在 GitHub Actions 里新建了一个 workflow写了一个步骤steps: - name: Checkout run: git checkout main你期待它像本地一样切到 main 分支然后开始构建。但实际运行结果却五花八门最常见的是fatal: not a git repository (or any of the parent directories): .git也有可能是fatal: could not read Username for https://github.com。有些同学排错半天最后发现 runner 环境里连一个.git目录都没有这才意识到 CI 机不是自己的电脑。GitHub Actions 的 runner 每次执行 job 时都会准备一个干净的工作环境。你可以把它理解成一台临时分配的虚拟机默认工作目录通常是/home/runner/work/仓库名/仓库名这个目录一开始是空的。你没有本地终端里那些已经配置好的 SSH key、git config、远程地址和登录凭据。所以在这个环境里直接写git checkout本质上是“在一个没有仓库对象的环境里执行 Git 子命令”自然无法成功。因此这篇文章首先要解决的问题就是消除“本地 Git 操作可以照搬到 CI”这个惯性误区。CI 环境里获取代码不是单纯的一个git clone或者git checkout它需要处理认证、目标提交、历史深度、子模块、LFS 等多个环节。而actions/checkout正是把这些环节封装成标准步骤的官方 action。读完第一节你应该建立第一个判断只要你在 GitHub Actions 的 workflow 里需要把代码取到 runner 工作区第一选择永远是actions/checkout而不是手动拼装 Git 命令。后续的所有参数和排错都建立在这样一个前提上。2. actions/checkout 与 git checkout概念辨析与选择逻辑2.1 两个不同层级的概念git checkout是 Git 自带的一个子命令。它做的事情主要有两类一是切换分支二是恢复工作区中的文件到某个提交版本。它改变的是本地仓库当前工作区的状态、HEAD 指针和索引状态。在本地开发中几乎每天都会用到但它依赖的前提是你当前已经在一个完整的 Git 仓库中并且本机有相应的认证凭据。actions/checkout则完全不同。它不是命令行工具而是 GitHub 提供的一个 Action 组件在 workflow 的 YAML 里通过uses: actions/checkoutv4这类语法引用。它本身是一段被封装好的逻辑内部会调用 Git 相关命令但对外暴露的是 action 参数。它解决的是“在一台全新的 runner 上如何安全、标准地拿到指定仓库的指定提交”这个任务。很多人在网上搜索git checkout problem时其实遇到了多种不同的问题。有人是本地切换分支不干净有人是 CI 中拉不到代码还有人是在 workflow 里写了 Git 命令但认证失败。这些问题看起来都带“checkout”关键词根因却不在同一个层级。先把概念区分开后面排错才不会把锅乱扣到某个工具上。2.2 为什么 workflow 里不能直接依赖 git clone 或裸的 git checkout从直觉上看git clone也可以拉代码而且似乎更简单。但放到 GitHub Actions 环境中直接使用裸git clone会面临几个实际问题。首先是认证。runner 上没有你的个人访问令牌也没有 SSH 私钥。即使仓库是公开的你也要能拼出正确的 URL如果是私有仓库裸命令大概率会直接要求输入用户名密码而 CI 环境里不会有人工交互。actions/checkout会自动使用 GitHub 提供的GITHUB_TOKEN把认证信息注入到 Git 命令中所以表面看起来“不用认证”就成功了。其次是版本一致性问题。GitHub Actions 的触发事件通常会带一个具体的提交 SHA比如 push 事件里有github.shapull_request 事件里有源分支最新的提交。actions/checkout默认会检出触发这个 workflow 的那个提交确保 CI 构建的代码和触发时刻保存一致。而直接git clone默认拿到的是默认分支的最新 HEAD两者可能完全不同。你在本地修复了一个 bug推上去之后 CI 却还在用旧代码这种情况往往就是这么来的。2.3 选择逻辑什么时候用哪个对比维度git checkoutgit cloneactions/checkout运行位置本地终端任意有 Git 的环境GitHub Actions runner主要目标切换分支 / 恢复文件克隆仓库获取指定提交到工作区认证支持依赖本机凭据依赖本机凭据自动注入 GITHUB_TOKEN默认提交当前分支 HEAD默认分支 HEAD触发本次 workflow 的提交子模块默认不递归默认不递归参数submodules可控制Git LFS默认不拉取默认不拉取参数lfs可控制推荐场景日常本地开发手动复制仓库GitHub Actions 工作流所以选择的逻辑其实非常简单在 GitHub Actions 的 YAML 里凡是需要“拉取代码到 runner 工作区”的步骤都使用actions/checkout至于git checkout可以在actions/checkout执行完之后作为后续 run 步骤中的一条命令来操作本地已经存在的仓库对象。也就是说两者不是非此即彼的替代关系而是不同生命周期阶段的不同工具。先有仓库才能谈得上git checkout切换分支。3. actions/checkout 的核心参数与运行机制3.1 常用参数actions/checkout的参数并不复杂但每个参数在真实项目中都有其存在的必要性。下面这份 YAML 展示了最常用的配置组合- name: Checkout uses: actions/checkoutv4 with: repository: your/repo ref: main token: ${{ secrets.GITHUB_TOKEN }} fetch-depth: 0 persist-credentials: true path: . submodules: recursive lfs: true clean: true接下来逐一拆解这些参数。repository参数用于指定要拉取的仓库默认是当前 workflow 所在的仓库格式通常是owner/repo。这个参数的存在意味着你可以在一个仓库的 workflow 中拉取另一个仓库的代码。这在文档仓库构建、多仓库联调、微服务批量构建等场景中非常有用。不过要注意跨仓库拉取私有仓库时必须提供一个对目标仓库有读取权限的 token。ref参数的作用是决定检出哪个 Git 引用可以是分支名、tag 或 commit SHA。默认情况下它使用触发 workflow 的那个 ref例如refs/heads/main或refs/tags/v1.0.0。这里最容易踩的坑是如果在 workflow 里写死了ref: develop那么后续每次执行都会拉取 develop 分支的最新提交而不是触发 workflow 的那个提交。对于需要精确复现的 CI 场景如果不确定该写什么优先使用默认值。token参数默认使用${{ secrets.GITHUB_TOKEN }}。GITHUB_TOKEN是 GitHub 自动创建的临时访问令牌会自动过期并且权限可以在仓库设置中控制。对于大多数仓库而言这个默认 token 已经有读取当前仓库代码的权限。如果 workflow 需要访问其他私有仓库就需要结合repository参数并提供更高权限的 PATPersonal Access Token。fetch-depth控制 Git 克隆的深度。默认值是 1也就是浅克隆只拉取最近一个提交。这样最快、占用磁盘最少适用于大多数构建任务。当你需要统计提交记录、计算差异文件、或者执行某些需要完整历史的 Git 操作时可以设置为 0表示拉取完整历史。设置成比如3则只拉取最近 3 个提交这是一种兼顾速度与信息量的折中方案。persist-credentials默认是true意味着 token 会被持久化到 runner 的 Git 配置中使得后续步骤执行git push等命令时不需要重新认证。如果你的 workflow 后续没有推送需求建议显式设置为false。这能减少 token 暴露在多个步骤中的风险尤其在自托管 runner 上安全性更重要。path指定代码存放的相对路径默认是当前工作目录。这个参数非常实用。当 workflow 需要同时拉取当前仓库和另一个仓库时可以用path: repo-a、path: repo-b把它们隔离到不同目录避免互相覆盖。submodules用于控制是否递归拉取子模块。可选值通常有true、recursive等。如果项目使用 Git Submodule但没有配置这个参数你会看到子模块目录存在却为空进而引发编译资源缺失、静态文件找不到等连锁问题。处理嵌套子模块时使用recursive会比较稳妥。lfs参数用于控制是否下载 Git LFS 大文件。如果项目用 Git LFS 管理二进制资源构建时又依赖这些文件需要设置为true。不设置的话Git LFS 文件可能只保留一个文本指针真正的文件内容不会出现在工作区。clean参数默认是true表示检出前清理工作目录中的残留文件。自托管 runner 环境下上一次构建可能留下大量文件如果不清理很容易造成“本地能过、CI 不能过”的假性失败。保持默认值通常是最安全的选择。3.2 运行机制它本质上做了什么理解actions/checkout的运行机制对排错非常有帮助。它在执行时大致会做这几件事根据repository和token构造带认证信息的远程地址。根据fetch-depth执行对应的 fetch 操作决定拉取的历史深度。根据ref切换到对应的提交并把工作区文件恢复出来。根据submodules和lfs决定是否拉取子模块和大文件。最后根据clean和path等参数调整工作区状态。这也是为什么你能在日志里看到Syncing repository、Checking out the ref、HEAD is now at这类关键字。看到这些输出说明 checkout 正在正常执行如果在这一步报错问题往往出在认证、仓库路径或 ref 名称而不是后面的构建命令。4. 环境准备与前置条件让 GitHub Actions 先跑起来4.1 账号和权限准备要使用actions/checkout首先需要一个 GitHub 账号和一个启用了 Actions 的仓库。公开仓库开箱即用你不需要额外配置GITHUB_TOKEN默认就有读取代码的权限。对于私有仓库需要确认仓库的 Actions 功能是开启状态并且默认的GITHUB_TOKEN权限设置正确。在仓库的Settings - Actions - General下可以设置 Workflow 的权限。这里有“Read repository contents permission”只读和“Read and write permissions”读写两种主要选项。如果只是让actions/checkout拉代码只读就足够了。如果你后续需要在 workflow 中创建 tag、推送提交那就需要开启读写权限但要注意这也会扩大 token 的暴露范围。如果 workflow 需要访问另一个私有仓库建议在Settings - Secrets and variables - Actions中创建一个 secret把具有repo权限的 PAT 放进去。不要在 YAML 里直接写 token这是最基本的底线。secret 在 GitHub 的网页界面中是隐藏的只有进入对应 job 运行时才会注入环境变量因此在日志中不会被直接看到。4.2 workflow 目录结构GitHub Actions 的工作流文件必须放在.github/workflows/目录下文件后缀是.yml或.yaml。一个典型项目目录如下my-project/ ├── .github/ │ └── workflows/ │ └── ci.yml ├── src/ │ └── ... └── package.json没有这个目录就手动创建文件命名没有硬性要求但建议使用有意义的名称比如ci.yml、build.yml、deploy.yml。工作流文件并不是推一次就能修改一次每次 push 到仓库后GitHub 都会重新解析 YAML所以如果你改了配置却发现 Actions 没有响应先看看是否真的推到了默认分支。4.3 runner 环境与 Git 版本GitHub 托管的 runner 预装了 Git操作系统镜像会保持 Git 版本更新到较新的程度大多数情况下你不需要手动安装。如果你使用自托管 runner需要自行保证 Git 版本足够新并检查 runner 工作目录的权限。自托管 runner 和官方 runner 的行为差异比较大尤其是在文件清理、环境变量和用户权限方面。在编写 workflow 时建议不要依赖当前 runner 的默认环境变量来做目录拼接。最稳妥的方式是在步骤中使用 GitHub Actions 提供的上下文例如${{ github.workspace }}它代表 checkout 之后工作目录的绝对路径。用这个变量引用代码路径比硬编码/home/runner/work要可靠得多。5. 完整示例从零编写可用的 CI 工作流5.1 最小示例拉取代码并运行测试下面是一份结合 Node.js 项目的最小 CI 示例。我会在注释里标明关键作用方便你直接复制到项目中改造成自己的流程# 文件路径.github/workflows/ci.yml name: CI on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: test: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 20 cache: npm - name: Install dependencies run: npm ci - name: Run tests run: npm test这段配置的含义是只要 main 或 develop 分支收到 push或者有人向 main 发起 pull_request就触发test这个 job。job 运行在ubuntu-latest上。Checkout code步骤会把当前仓库的代码拉到 work 目录后面的Setup Node.js安装 Node.js 20 并启用 npm 缓存npm ci根据锁文件安装依赖最后npm test执行测试。这里最核心的一步就是uses: actions/checkoutv4。如果没有这一步后面的npm ci找不到package.jsonnpm test也找不到src目录你会看到一堆No such file or directory的报错。所以对于大多数项目checkout 都应当是 job 中最早的关键前置步骤。另外本文里的actions/checkoutv4是一个常用 tag实际使用时建议到actions/checkout仓库查看当前维护状态选择稳定的版本。教程的重点是通用思路版本 tag 可以按项目实际情况调整。5.2 高级示例拉取多个仓库并使用不同目录现实项目里经常出现“一个 CI 流程需要同时拉取主代码和另一个私有基础库”的需求。下面的示例展示了如何用path和repository参数完成多仓库协作# 文件路径.github/workflows/multi-repo.yml name: Multi Repo Build on: workflow_dispatch: jobs: build: runs-on: ubuntu-latest steps: - name: Checkout main repo uses: actions/checkoutv4 with: path: main-repo - name: Checkout docs repo uses: actions/checkoutv4 with: repository: my-org/my-docs token: ${{ secrets.DOCS_REPO_TOKEN }} path: docs-repo - name: Show directories run: | ls -la main-repo ls -la docs-repo这里需要注意几个关键点。第一个Checkout main repo使用的是当前仓库path: main-repo会把代码放到工作目录下的main-repo子目录。第二个Checkout docs repo拉取的是my-org/my-docs仓库并且通过token: ${{ secrets.DOCS_REPO_TOKEN }}传入一个有权限的 PAT。如果你不提供 token即使仓库存在私有仓库也无法访问。将多个仓库放到不同目录可以避免文件覆盖也让后续步骤能清楚地引用各自的代码路径。如果你需要的是“把多个仓库合并进同一个目录”那是另一个复杂问题actions/checkout 的path参数并不适合因为每个 action 会独立执行 clean 和 checkout容易互相覆盖。5.3 高级示例完整历史、子模块与 LFS下面是一个面向复杂仓库的配置适合需要完整历史、子模块和 Git LFS 的项目# 文件路径.github/workflows/full-checkout.yml name: Full Checkout on: pull_request: jobs: build: runs-on: ubuntu-latest steps: - name: Checkout with full history uses: actions/checkoutv4 with: ref: ${{ github.event.pull_request.head.sha }} fetch-depth: 0 submodules: recursive lfs: true token: ${{ secrets.GITHUB_TOKEN }}这段配置的逻辑是每当有 pull_request 事件时检出 PR 来源分支的最新提交 SHA。fetch-depth: 0拉取完整历史适合需要做代码差异分析、代码覆盖率增量、lint 差异对比等任务。submodules: recursive递归拉取子模块lfs: true在构建前下载 Git LFS 大文件。如果在使用这个配置后子模块目录仍然是空的优先检查你的仓库是否真的包含.gitmodules文件以及子模块地址是否是 runner 能访问的地址。LFS 文件没有下载时通常表现为文件内容是一段大小很小的文本指针而不是真实的二进制内容看到这种迹象就应当回头检查lfs参数。5.4 一个 Java/Maven 项目的对照参考如果你用的是 Java下面这个示例也可以对照使用# 文件路径.github/workflows/maven-ci.yml name: Maven CI on: push: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv4 - name: Set up JDK 17 uses: actions/setup-javav4 with: distribution: temurin java-version: 17 cache: maven - name: Build with Maven run: mvn -B package --no-transfer-progress这个示例说明的核心事实是无论项目技术栈是什么checkout 的思路完全一致。先取代码再搭工具链再构建最后测试或打包。唯一需要替换的是后续步骤里的工具链安装命令和构建命令。6. 运行验证与关键日志解读6.1 如何触发和查看运行结果将 YAML 文件推送到仓库后进入仓库的Actions标签页你会看到对应的工作流名称。点击工作流名称再点击具体的运行记录可以看到每个 job 的每个步骤列表。一个成功的Checkout code步骤通常会在展开后看到类似下面的日志片段Syncing repository: your-name/your-repo Git commit message: fix: update ci config ... HEAD is now at 7a3f5a2 fix: update ci configHEAD is now at ...这一行是最明确的成功信号。它表示 checkout 已经将工作区切换到了某个具体的 commit SHA。看到这行日志说明actions/checkout的主要使命已经完成。6.2 判断成功与失败的维度成功的标志不只是“job 是绿色”。你需要检查两件事第一Checkout code步骤本身是否通过第二Checkout code之后的步骤能否读到项目文件。如果 job 失败在Run tests说明 checkout 阶段是好的问题在依赖安装或命令本身如果失败点就是Checkout code那就要优先排查认证、仓库地址和 ref。6.3 常见日志特征速查Could not find ref developref参数写错了或目标分支不存在。Authentication failedtoken 无效或权限不足。fatal: unable to access ... 403私有仓库访问权限范围不够。Warning: submodule ... couldnt be found子模块地址或 token 权限有问题。LFS files not found没有开启lfs: true或者 LFS 文件尚未上传到远端。7. 常见问题与排查方法下面的表格汇总了我见过的高频场景。你可以把它当作一份排错清单遇到问题时逐行对照。问题现象可能原因排查方式解决方案fatal: not a git repositoryrunner 上没有仓库却在 run 里直接执行 git 命令检查步骤顺序和工作目录在步骤开头加入actions/checkoutfatal: could not read Username没有使用actions/checkout或persist-credentials被错误关闭检查是否手动执行 git clone/pull改用actions/checkout确认 token 参数remote: Repository not found.私有仓库 token 权限不足用 token 在本地测试git ls-remote使用有repo权限的 PATError: Input required and not supplied: token拉取非当前仓库时没有显式传 token检查repository参数和目标仓库访问权限为 secret 添加 tokenworkflow 总是拿到旧代码ref写死成某个分支或fetch-depth配置不当查看Checkout code日志中的 commit SHA使用默认ref或按需设置深度子模块目录为空没有配置submodules参数检查仓库是否有.gitmodules设置submodules: recursiveLFS 文件缺失没有配置lfs: true检查文件是否为 LFS 指针设置lfs: true后续步骤找不到代码文件checkout 放在了错误位置或path配置不对执行ls查看工作目录调整步骤顺序和path参数除了表格里的情况还有一个很隐蔽的问题需要单独强调actions/checkout默认会清理工作目录。如果你使用自托管 runner并且在同一台机器上并行跑多个 job可能会出现文件互相覆盖。遇到这种情况不要只在 workflow 层面加clean: false 更稳妥的做法是给每个 job 配置独立的临时目录或者使用官方托管的 runner。另一个常见误解是“在 workflow 里执行git checkout branch后后续步骤就能基于那个分支构建”。实际上actions/checkout已经处于 detached HEAD 状态它指向的是某个具体的 commit SHA而不是“符号分支”。如果你真的需要在 CI 中临时切换分支首先确认actions/checkout已经把仓库拉下来了然后在 run 中执行git checkout some-branch才是合理的操作。否则你会看到很多“branch not found”或“detached HEAD”提示。8. 最佳实践与工程建议8.1 让 checkout 尽量靠前我建议把actions/checkout放在每个 job 的前部。原因很简单后面的所有步骤几乎都依赖代码存量。虽然像actions/setup-node、actions/setup-java这类工具不依赖代码目录把工具链放在 checkout 之前也不是绝对不行但为了避免搞混工作目录统一保持“先 checkout再 setup再执行构建”的顺序团队成员理解起来更容易排查问题时也更省心。8.2 默认浅克隆按需加深fetch-depth: 1是大多数 CI 流程的最佳默认值。浅克隆不仅快而且不会把仓库历史全部拉到 runner 上减少带宽和磁盘消耗。只有在确实需要比较多个提交、计算改动文件、生成覆盖率增量报告时才需要提升深度。如果只想获取最近几条提交可以用具体的数字比如fetch-depth: 5。不要盲目把fetch-depth: 0写进所有 workflow除非你有明确需求。8.3 控制 token 暴露面GITHUB_TOKEN是自动生成、自动过期的这比手动创建 PAT 更安全。但在需要跨仓库访问时PAT 不可避免。使用 PAT 的时候请记住三个原则只能通过 GitHub Secrets 注入不要硬编码。尽量限制 PAT 的仓库范围和权限 scope。定期轮换并且把使用情况纳入组织审计。persist-credentials也要有意识地控制。如果构建过程不需要git push、不需要发布 tag建议设置persist-credentials: false。这样后续步骤不会继承无关的认证信息。相反如果部署步骤需要把构建产物提交回仓库就保持为true或单独提供一个有写权限的 token。8.4 结合缓存提升效率actions/checkout只负责代码获取不负责依赖缓存。对于依赖安装比较重的项目建议结合actions/setup-node、actions/setup-java和actions/cache做依赖缓存。典型的执行顺序是checkout - setup 工具链 - 恢复缓存 - 安装依赖 - 构建测试。缓存能显著缩短 workflow 执行时间尤其是在大型 Spring Boot 服务或前端 monorepo 项目中。要注意的是不要试图用 cache action 缓存 checkout 生成的.git目录。Git 仓库的完整性和版本一致性比缓存收益重要得多缓存.git可能导致不同 commit 之间状态混乱反而引入更难排查的问题。8.5 自托管 runner 的清理策略自托管 runner 不会像官方 runner 那样每次 job 结束后自动清理。建议在 workflow 中显式设置clean: true并在关键步骤里使用固定工作目录。更稳妥的做法是使用官方 runner 或者定期清理 runner 上的 Python/Gradle/npm 缓存目录。如果多个 workflow 共用同一台 runner还要考虑并发时的目录隔离避免不同分支构建互相影响。8.6 分支保护与权限的配合分支保护规则和 Actions 权限是两个独立但互相影响的概念。如果仓库启用了分支保护那么来自pull_request事件的 workflow 拿到的GITHUB_TOKEN默认是只读的不能向受保护分支推送代码。如果你需要“验证通过后自动合并”或“自动更新依赖 PR”通常
