CI에서만 git describe와 변경 파일 목록이 비어 있던 이유

문제 발생

릴리스 버전을 태그에서 만드는 스크립트가 CI에서만 실패했습니다.

fatal: No names found, cannot describe anything.

같은 명령이 로컬에서는 정상이었습니다. 변경된 파일만 골라 검사하려고 넣은 git diff origin/main...HEAD도 CI에서는 빈 결과이거나 오류였습니다.

원인 분석

CI가 **얕은 클론(shallow clone)**을 쓰기 때문입니다. actions/checkout의 fetch-depth 설명은 짧고 분명합니다 — 가져올 커밋 수. 0은 모든 브랜치와 태그의 전체 이력을 의미합니다. 기본값: 1. 태그도 마찬가지입니다 — fetch-tags: fetch-depth > 0이어도 태그를 가져올지 여부. 기본값: false.

즉 CI 작업 공간에는 커밋 한 개와 태그 0개만 있습니다. git describe는 이력을 거슬러 올라가며 가장 가까운 태그를 찾는 명령이라 찾을 것이 없고, origin/main은 아예 가져와 있지 않습니다.

Git 쪽 설명도 같습니다. git clone --depth는 지정한 커밋 수로 이력을 잘라낸 얕은 클론을 만들며, --no-single-branch를 주지 않는 한 --single-branch를 함의합니다. 브랜치 하나, 커밋 몇 개만 있는 저장소라는 뜻입니다.

이게 기본값인 이유는 타당합니다. 큰 저장소에서 전체 이력을 받는 건 대부분의 job에 불필요한 시간이고, 대부분의 빌드는 최신 커밋의 파일만 있으면 됩니다. 문제는 이력이 필요한 명령이 오류 대신 조용히 다른 답을 낸다는 점입니다.

해결 방안

1. 이력이 필요한 job에서만 전체를 가져옵니다. 모든 job에 붙이면 CI가 전반적으로 느려집니다.

- uses: actions/checkout@v5
  with:
    fetch-depth: 0

2. 태그만 필요하면 태그만 가져옵니다.

- uses: actions/checkout@v5
  with:
    fetch-tags: true

3. 비교 대상 브랜치는 명시적으로 가져옵니다. 전체 이력이 부담이면 필요한 만큼만 받습니다.

git fetch --no-tags --depth=50 origin main
git diff origin/main...HEAD --name-only

4. 이미 얕은 상태를 로컬에서 풀어야 하면 --unshallow입니다.

git fetch --unshallow

5. CI에서만 나는 이 류의 차이를 스크립트가 스스로 말하게 합니다. git rev-parse --is-shallow-repository가 true면 이력 기반 명령을 실행하기 전에 명확한 메시지로 실패시키는 편이, 빈 결과를 정상으로 착각하는 것보다 낫습니다.

공식 문서

• Git: git-clone — --depth
• actions/checkout — inputs