GitHub Actions 캐시를 걸었는데 매번 다시 받는 이유

문제 발생

CI 파이프라인에 actions/cache로 의존성 캐시를 추가했는데, 실행 시간이 전혀 줄어들지 않아 확인해보니 매번 캐시 미스가 나고 있었습니다.

- uses: actions/cache@v4
  with:
    path: node_modules
    key: node-modules-cache # 항상 같은 key

원인 분석

actions/cache는 key가 이전에 저장된 캐시와 정확히 일치해야 히트합니다. 위 예시처럼 key를 고정 문자열로 두면 첫 실행에서는 캐시를 만들지만, 그 캐시는 이후 절대 갱신되지 않습니다 — actions/cache는 캐시가 이미 있으면 저장을 건너뛰기 때문에, package-lock.json이 바뀌어 의존성이 달라져도 옛날 node_modules를 계속 그대로 씁니다. 반대로 lockfile 해시를 key에 넣지 않으면 새로운 의존성이 추가됐는데도 오래된 캐시가 복원되어 빌드가 조용히 잘못된 상태로 진행될 위험도 있습니다.

반대로 매번 다른 key(예: github.run_id처럼 실행마다 바뀌는 값)를 쓰면 캐시가 절대 재사용되지 않습니다 — 매번 새로 만들고 다음 실행은 그 캐시를 찾지 못합니다.

해결 방안

1. key에는 캐시 내용이 실제로 바뀌는 시점을 반영하는 값을 넣습니다 — 의존성 캐시라면 lockfile의 해시가 정석입니다.

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

2. restore-keys는 정확히 일치하는 키가 없을 때 접두사가 일치하는 가장 최근 캐시를 부분적으로라도 복원해줍니다 — lockfile이 살짝 바뀐 정도라면 완전히 새로 받는 것보다 이전 캐시를 베이스로 부분 갱신하는 게 더 빠릅니다.
3. 여러 OS/버전을 매트릭스로 빌드한다면 key에 runner.os나 언어 버전을 포함시켜 서로 다른 환경의 캐시가 섞이지 않도록 합니다.
4. actions/setup-node의 cache: 'pnpm'/cache: 'npm' 옵션처럼, 언어별 공식 setup 액션이 제공하는 내장 캐시 기능을 쓰면 이런 key 설계를 직접 하지 않아도 되는 경우가 많습니다 — 가능하면 이쪽을 우선 검토합니다.

공식 문서

• GitHub Actions Docs: Caching dependencies