GitHub Actions 의존성 캐시 키를 lockfile 하나로만 두지 않은 이유

CI만 가끔 예전 패키지로 빌드됐다

앱과 관리자 패키지가 함께 있는 저장소에서 의존성을 업데이트했다. 로컬과 캐시 없는 CI는 통과했는데 캐시가 맞은 실행에서만 타입 오류가 났다. 원인은 루트 package-lock.json만 캐시 기준에 넣고 apps/admin/package-lock.json은 빼둔 설정이었다.

캐시는 설치 시간을 줄이는 도구이지 정답을 보장하지 않는다. 무엇이 바뀌면 새 캐시를 써야 하는지 키에 반영해야 한다.

저장소 구조를 기준으로 잡았다

.
├── package-lock.json
├── apps/web/package-lock.json
└── apps/admin/package-lock.json

actions/setup-node를 쓴다면 실제 lockfile을 모두 cache-dependency-path에 지정할 수 있다.

- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: npm
    cache-dependency-path: |
      package-lock.json
      apps/web/package-lock.json
      apps/admin/package-lock.json

- run: npm ci
  working-directory: apps/web

pnpm이나 yarn도 원리는 같다. 설치 명령의 패키지 관리자와 캐시 대상 lockfile이 일치해야 한다.

캐시 삭제는 원인 확인 뒤에 했다

문제를 재현할 때는 임시 캐시 경로로 설치해 기존 캐시와 비교했다.

- run: npm cache verify
- run: npm ci
  env:
    npm_config_cache: ${{ runner.temp }}/npm-cache

새 캐시에서만 성공한다면 코드를 고치기 전에 무효화 기준을 확인할 신호다. 캐시를 전부 지우면 당장은 통과해도 설정 오류는 남는다.

남긴 기준

• 빌드하는 패키지마다 lockfile이 키에 포함되는가?
• 캐시 없이도 CI가 통과하는가?
• 캐시 문제를 이유로 npm install로 바꾸지 않았는가?

히트율보다 잘못된 캐시를 쓰지 않는 일이 우선이다. 가끔만 실패하는 CI라면 코드보다 캐시가 무엇을 기준으로 살아남는지부터 읽어본다.