GitHub Actions 캐시가 안 먹힐 때 점검: pnpm/npm/gradle key 설계와 cache miss 원인

GitHub Actions 캐시가 안 먹힐 때 점검: pnpm/npm/gradle key 설계와 cache miss 원인

CI가 느린 이유 1순위는 의존성 설치입니다. 그런데 캐시를 넣었는데도 매번 install이 도는 경우가 많습니다. 이 글은 GitHub Actions 캐시가 안 먹히는 이유를 '키 설계' 관점에서 정리하고, pnpm/npm/gradle 예시를 제공합니다.

캐시는 결국 key hit/miss 게임이고, key를 어떻게 묶느냐가 성능과 안정성을 좌우합니다.

옵션/핵심 요소(3~6개)

항목	의미	언제 쓰는지(실무 상황)
path	캐시할 디렉터리	pnpm store, npm cache, gradle caches 등 실제 설치 비용을 줄이는 위치
key	캐시 식별자	lockfile이 바뀌면 무효화되도록 hashFiles를 포함
restore-keys	부분 매칭	완전 일치가 없어도 비슷한 캐시를 가져와 체감 속도 개선
OS/버전 결합	환경 차이 반영	ubuntu/macos, node 버전 차이로 깨지는 캐시를 분리
캐시 위치 검증	정말 쓰는 위치인지 확인	pnpm store 경로/gradle user home이 실제 런너에서 다른 경우

실전 예시: pnpm 캐시(대표 패턴)

# .github/workflows/ci.yml (발췌)
- uses: actions/setup-node@v4
  with:
    node-version: '20'

- name: Get pnpm store path
  id: pnpm-store
  run: echo "store_path=$(pnpm store path)" >> $GITHUB_OUTPUT

- uses: actions/cache@v4
  with:
    path: ${{ steps.pnpm-store.outputs.store_path }}
    key: pnpm-${{ runner.os }}-node20-${{ hashFiles('pnpm-lock.yaml') }}
    restore-keys: |
      pnpm-${{ runner.os }}-node20-

- run: pnpm install --frozen-lockfile

문제 상황(정확히 1개)

상황: 캐시 step 로그에 Cache not found for input keys가 계속 뜨고, 매번 설치 시간이 동일하다.

원인: key에 포함한 lockfile 경로가 실제와 달라 hashFiles가 항상 빈 값이 되거나, 캐시 path가 실제로 의존성이 저장되는 위치가 아니다. 또는 OS/Node 버전이 바뀌면서 다른 키로 분리되어 hit가 불가능해졌다.

해결: 1) lockfile 경로를 정확히 지정하고 2) 캐시할 path를 런너에서 출력해 검증하며 3) key에 OS/툴 버전을 포함해 의도적으로 분리한다.

예방 팁: CI에서 캐시 hit/miss를 metrics로 보고, key를 '너무 넓게' 잡아 깨지는 캐시를 재사용하지 않도록(안정성)와 '너무 좁게' 잡아 hit가 0이 되지 않도록(성능) 균형을 맞춘다.

참고/출처

• GitHub Actions: cache action
• GitHub Docs: Caching dependencies