Bitbucket Pipeline报‘fatal: Not a valid object name HEAD’错误排查与修复

Bitbucket Pipelines默认采用**浅克隆（--depth 1）**拉取代码，仅获取最新提交快照而非完整仓库历史。当动态生成report.json后，git status触发Git LFS的clean过滤器时，LFS需要访问HEAD引用对应的完整元数据，但浅克隆环境下部分Git/LFS元数据缺失，导致过滤器无法识别HEAD的有效对象，从而抛出错误。

本地环境是完整克隆，包含所有Git历史和LFS元数据，因此LFS过滤器能正常工作。

以下是几种安全高效的修复方式，可按需选择：

方案1：排除构建生成文件的LFS规则（推荐） #

report.json是构建过程中动态生成的临时文件，无需通过Git LFS管理，直接在.gitattributes中添加例外规则：

*.json filter=lfs diff=lfs merge=lfs -text
!report.json filter= diff= merge= text

这样Git会将report.json视为普通文本文件，不会触发LFS过滤器。

方案2：修改Bitbucket Pipelines的克隆策略 #

如果必须保留所有.json文件的LFS规则，可将克隆方式改为完整克隆，确保LFS能获取完整元数据。在bitbucket-pipelines.yml中添加clone配置：

clone:
  depth: full

pipelines:
  default:
    - step:
        name: Build Step
        script:
          - echo '{"status":"compiled"}' > report.json
          - git status

注意：完整克隆会拉取所有历史记录，可能增加构建时间，适合仓库较小的场景。

方案3：在构建步骤中显式初始化Git LFS #

在执行生成文件和git status前，显式初始化Git LFS并拉取必要元数据：

image: python:3.11
pipelines:
  default:
    - step:
        name: Build Step
        script:
          - git lfs install --local
          - git lfs pull
          - echo '{"status":"compiled"}' > report.json
          - git status

此方法确保LFS过滤器能正确识别仓库状态，解决浅克隆导致的元数据缺失问题。

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