Azure DevOps自托管代理默认检出失败：HEAD歧义与Git重置/清理错误

使用自托管代理运行Azure DevOps管道，管道定义在TestRepo仓库的YAML中，但默认检出步骤失败，报错如下：

fatal: ambiguous argument 'HEAD': unknown revision or path not in the working tree. Use '--' to separate paths from revisions, like this: 'git <command> [<revision>...] -- [<file>...]' ##[warning]Unable to run "git clean -ffdx" and "git reset --hard HEAD" successfully, delete source folder instead.

相关日志显示Git版本为2.47.0.windows.2，执行git reset --hard HEAD时触发错误，推测是在拉取提交前就执行了重置操作。

使用的YAML脚本如下：

trigger: none

pool:
  name: 'SelfHostedAgents'

variables:
  branch: main

jobs:
  - job: Build
    steps:
      # 1) debug: show that the token is injected
      - script: |
          echo "SYSTEM_ACCESSTOKEN = $SYSTEM_ACCESSTOKEN"
        displayName: 'Dump System.AccessToken'
        env:
          SYSTEM_ACCESSTOKEN: $(System.AccessToken)

      # 2) your real build steps
      - script: echo Hello, world!
        displayName: 'Run a one-line script'

      - script: |
          echo Add other tasks to build, test, and deploy your project.
          echo See https://aka.ms/yaml
        displayName: 'Additional guidance'

已尝试的操作：

• 确认代理可手动克隆仓库
• 尝试禁用默认检出（多仓库场景不允许）
• 手动指定检出仍报错

疑问：

1. 为何Azure DevOps在拉取提交前重置HEAD？
2. 如何阻止该行为？
3. 多仓库下如何完全禁用默认获取源步骤？

1. 为何会在拉取前执行git reset --hard HEAD？ #

Azure DevOps的默认「获取源」步骤，核心目的是保证每次构建的工作区干净，避免残留文件干扰结果。它的逻辑是：如果代理工作目录里已经存在该仓库的本地副本，会先执行git clean和git reset --hard HEAD重置到干净状态，再拉取最新代码。

但如果本地副本是空仓库（没有任何提交记录），或者HEAD指向的引用不存在，就会触发unknown revision or path not in the working tree错误——因为此时HEAD没有对应的提交对象可重置。常见触发场景包括：代理首次运行该管道时，仓库目录被创建但还没拉取代码；或者之前的构建异常终止，导致仓库处于未初始化/空仓库状态。

2. 如何阻止这个提前重置的行为？ #

有两种实用方案：

• 方案一：修改默认检出的清理策略
  在YAML中添加checkout配置，将clean参数设为false，跳过预拉取的重置和清理操作：

  jobs:
    - job: Build
      steps:
        - checkout: self
          clean: false
  

  这种方法会保留工作区现有文件，适合不需要完全干净环境的场景，同时能避免空仓库下的HEAD错误。

• 方案二：手动完成仓库拉取与初始化
  先禁用默认检出，再通过脚本手动克隆/拉取仓库，完全掌控Git操作：

  trigger: none
  
  pool:
    name: 'SelfHostedAgents'
  
  variables:
    branch: main
  
  jobs:
    - job: Build
      steps:
        - checkout: none # 完全禁用默认检出
        - script: |
            # 检查本地仓库是否存在，不存在则克隆
            if [ ! -d "TestRepo/.git" ]; then
              git clone https://dev.azure.com/your-org/your-project/_git/TestRepo
              cd TestRepo
            else
              cd TestRepo
              git fetch origin $(branch)
            fi
            git checkout $(branch)
            git reset --hard origin/$(branch)
          displayName: 'Manual Git Checkout'
        # 后续构建步骤...
  

3. 多仓库场景下完全禁用默认获取源步骤？ #

多仓库时，默认会检出YAML所在的仓库（self），要完全禁用所有默认的「获取源」步骤，需要：

1. 在job级别设置checkout: none，禁用所有默认检出
2. 手动添加每个需要的仓库的拉取脚本，或者使用checkout任务逐个指定仓库并配置参数

示例1：全手动拉取多仓库 #

trigger: none

pool:
  name: 'SelfHostedAgents'

variables:
  branch: main

jobs:
  - job: Build
    checkout: none # 禁用所有默认检出
    steps:
      # 拉取第一个仓库
      - script: |
          git clone https://dev.azure.com/your-org/your-project/_git/Repo1
          cd Repo1
          git checkout $(branch)
        displayName: 'Checkout Repo1'
      # 拉取第二个仓库
      - script: |
          git clone https://dev.azure.com/your-org/your-project/_git/Repo2
          cd Repo2
          git checkout $(branch)
        displayName: 'Checkout Repo2'
      # 后续构建步骤...

示例2：用checkout任务逐个配置 #

jobs:
  - job: Build
    checkout: none
    steps:
      - checkout: Repo1
        clean: false
        path: 'Repo1'
      - checkout: Repo2
        clean: false
        path: 'Repo2'

内容的提问来源于stack exchange，提问作者Pankaj Wagh