CircleCI v2.1 config.yml中如何检出指定分支而非当前分支

常见踩坑现象 #

• 直接使用无参数的- checkout步骤，只会自动检出触发本次流水线的对应分支，无法固定为指定分支（如master）
• 在默认checkout步骤后追加run: git checkout master，UI显示分支切换成功，但后续打包、归档等步骤仍使用触发分支的代码，配置不生效
• 删除checkout步骤、仅保留手动执行git checkout master的逻辑，运行时报错fatal: not a git repository (or any of the parent directories): .git，流程直接中断

问题根因 #

• 跳过checkout步骤的场景下，CircleCI运行容器初始状态不会自动拉取代码仓库，本地不存在.git目录，自然无法执行任何git命令
• 手动切换分支不生效的场景下，默认checkout只会拉取当前触发分支的提交内容，没有同步目标分支的远程代码引用，直接执行git checkout master既没有拉取目标分支的最新提交，也可能因为缺少分支引用切到无效分支，最终导致后续步骤拿到的还是旧的触发分支代码

注意：所有手动git操作的前提，是必须先通过checkout步骤完成本地仓库的初始化，不能跳过checkout直接执行git命令。

正确配置方案 #

方案1：通过checkout内置参数直接指定检出分支 #

这是最简洁的实现方式，不需要额外写手动git命令，直接给checkout步骤传入目标分支参数即可，示例配置：

steps:
  - checkout:
      name: 检出master分支代码
      revision: master

该能力为CircleCI原生支持，会自动完成远程仓库拉取、指定分支代码检出的全流程，后续步骤拿到的代码会完全匹配目标分支的最新状态，不会出现切换失效的问题。

方案2：需保留默认检出逻辑时的正确分支切换写法 #

如果业务流程需要先拉取触发分支的代码做前置校验，再切换到master分支执行后续操作，需要在切换前补全远程引用拉取动作，不能直接执行git checkout master，参考写法：

steps:
  # 先执行默认checkout初始化本地仓库
  - checkout
  - run:
      name: 切换并拉取master分支最新代码
      command: |
        # 先拉取远程master的完整提交引用
        git fetch origin master
        # 基于拉取的引用切换分支
        git checkout master
        # 同步分支最新提交
        git pull origin master

内容的提问来源于stack exchange，提问作者Jay Shah