Azure Pipeline未拉取完整代码库的问题排查与解决求助

问题描述 #

近期发现Azure DevOps的Pipeline未从Azure仓库拉取完整源代码，Pipeline配置如下：

stages:
  - stage: build_container
    displayName: "Build container"
    jobs:
      - job: create_container
        pool:
          name: Default
          demands:
            - Agent.Name -equals agent.linux
        steps:
          - checkout: self
            clean: true
            fetchTags: false
            lfs: false
            persistCredentials: true
            submodules: false
            continueOnError: false
            displayName: checkout repo
            name: checkout
            retryCountOnTaskFailure: 4

          - pwsh: |
              Set-Content -Path "$(System.DefaultWorkingDirectory)/agent/config/config.json" -Value 'some config'

执行时出现错误：

##[error]Cannot find path 'C:\AzureAgent\_work\3\s\agent\config\config.json' because it does not exist.

登录自托管代理机器后发现，C:\AzureAgent\_work\3\s目录仅包含README.md等根文件，不存在仓库中已有的agent等文件夹，但Checkout步骤执行成功且无报错。

可能的原因 #

• 分支匹配错误：Pipeline拉取的分支与预期不符，agent文件夹仅存在于特定分支，而当前Pipeline默认拉取的分支不包含该目录。
• 浅克隆限制：Azure DevOps默认采用浅克隆（仅拉取最近少量提交），若agent文件夹是通过历史提交、分支合并或重命名操作添加的，浅克隆可能无法获取完整目录。
• 自托管代理工作目录异常：尽管设置了clean: true，但代理工作目录可能存在缓存残留、权限不足等问题，导致Checkout步骤未彻底清理并拉取完整代码。
• 子模块配置冲突：若agent是仓库的子模块，但Pipeline中submodules: false的配置会阻止子模块内容拉取（需结合仓库实际结构确认）。

修复方法 #

1. 指定目标分支拉取
   在Checkout步骤中显式声明包含agent文件夹的分支，确保拉取正确代码：

   - checkout: self
     clean: true
     fetchTags: false
     lfs: false
     persistCredentials: true
     submodules: false
     continueOnError: false
     displayName: checkout repo
     name: checkout
     retryCountOnTaskFailure: 4
     ref: refs/heads/your-target-branch  # 替换为实际分支名
   

2. 禁用浅克隆
   添加fetchDepth: 0参数强制拉取完整仓库历史，避免浅克隆导致的文件缺失：

   - checkout: self
     clean: true
     fetchTags: false
     lfs: false
     persistCredentials: true
     submodules: false
     continueOnError: false
     displayName: checkout repo
     name: checkout
     retryCountOnTaskFailure: 4
     fetchDepth: 0  # 禁用浅克隆，拉取完整仓库
   

3. 清理代理工作目录并验证权限

   • 手动删除代理工作目录下的对应任务文件夹（如C:\AzureAgent\_work\3），重新运行Pipeline。
   • 确认代理运行账户对C:\AzureAgent\_work目录拥有完整读写权限，避免因权限不足导致文件无法写入。

4. 检查子模块配置（若适用）
   若agent是仓库子模块，将submodules: false改为submodules: true，确保子模块内容被拉取：

   - checkout: self
     clean: true
     fetchTags: false
     lfs: false
     persistCredentials: true
     submodules: true  # 启用子模块拉取
     continueOnError: false
     displayName: checkout repo
     name: checkout
     retryCountOnTaskFailure: 4
   

内容的提问来源于stack exchange，提问作者Alex F