답부터 말하면, GitHub Actions pnpm 캐시 설정은 Node 프로젝트에서 pnpm 의존성 설치 시간을 줄이기 위해 actions/setup-node의 캐시 옵션과 pnpm/action-setup, 잠금 파일 기준 키를 함께 맞추는 방식으로 시작하면 된다. 핵심은 캐시가 만능 가속 장치가 아니라, 같은 잠금 파일과 같은 패키지 매니저 조건에서 반복 다운로드를 줄이는 장치라는 점이다. 먼저 저장소의 패키지 매니저 버전을 고정하고, 워크플로 파일에서 Node 버전, pnpm 활성화, 캐시 경로, 설치 명령을 같은 순서로 정리하면 실패 원인을 빠르게 좁힐 수 있다.
요약: pnpm 버전 고정 → setup-node 캐시 활성화 → pnpm-lock.yaml 기준으로 키 구성 → install은 frozen lockfile로 실행 → 첫 실행과 재실행 시간을 비교한다. GitHub 공식 문서는 Node 빌드 워크플로와 의존성 캐싱 기준을 따로 설명하므로, 두 문서를 함께 보며 운영하는 것이 안전하다.
왜 pnpm 캐시를 먼저 정리해야 하나
CI가 느린 팀은 빌드 도구보다 의존성 설치 단계에서 시간을 많이 잃는 경우가 많다. pnpm은 전역 저장소와 심볼릭 연결 구조를 쓰기 때문에 npm과 같은 감각으로 캐시를 잡으면 기대만큼 빨라지지 않을 수 있다. 저장소 안에 여러 앱이 있는 모노레포라면 패키지 잠금 파일 변경, Node 버전 변경, 워크스페이스 필터 변경이 모두 설치 결과에 영향을 준다. 그래서 캐시 설정은 속도 팁이 아니라 배포 흐름의 재현성을 확인하는 체크 항목으로 다루는 편이 좋다.
기본 워크플로 구조
가장 단순한 흐름은 checkout, pnpm 준비, Node 준비, 의존성 설치, 테스트 또는 빌드 순서다. GitHub Actions에서 Node 프로젝트를 다룰 때는 checkout으로 소스 코드를 가져온 뒤 setup-node로 Node 버전을 맞춘다. pnpm은 Corepack으로 활성화하거나 pnpm/action-setup 액션을 사용할 수 있다. 팀에서 이미 packageManager 필드를 쓰고 있다면 그 버전을 기준으로 맞추는 것이 관리하기 쉽다.
setup-node cache 옵션 이해
setup-node에는 패키지 매니저별 캐시 옵션이 있다. pnpm을 지정하면 pnpm 저장소 관련 캐시를 복원하고 저장하는 흐름을 자동으로 다룰 수 있다. 다만 프로젝트 구조가 단순하지 않다면 cache-dependency-path를 명시해 잠금 파일 위치를 알려주는 것이 좋다. 루트에 pnpm-lock.yaml이 하나 있으면 간단하지만, 하위 폴더별 잠금 파일을 쓰는 구조라면 경로를 명확히 적어야 엉뚱한 캐시가 재사용되는 일을 줄일 수 있다.
모노레포에서 경로를 잡는 방법
모노레포는 패키지 수가 많아 작은 설정 차이가 큰 대기 시간으로 이어진다. 먼저 루트에서 모든 앱을 관리하는지, 앱별로 독립 실행하는지 나눈다. 루트 잠금 파일 하나를 기준으로 한다면 cache-dependency-path는 루트 파일을 가리키면 된다. 반대로 앱 폴더별로 실행한다면 워크플로의 working-directory와 캐시 기준 파일을 같은 기준으로 맞춘다. 이 두 값이 어긋나면 설치 명령은 하위 폴더에서 실행되는데 캐시는 루트 변경만 보고 움직이는 식의 혼선이 생긴다.
실무용 YAML 예시
아래 예시는 루트에 pnpm-lock.yaml이 있고 Node 20을 쓰는 저장소를 기준으로 한다. 실제 저장소에서는 브랜치 보호 규칙, 테스트 명령, 빌드 산출물 업로드 여부에 맞춰 단계를 더하거나 줄이면 된다. 중요한 것은 캐시 설정을 추가한 뒤 바로 복잡한 배포까지 붙이지 말고, install과 test 단계에서 먼저 시간이 안정적으로 줄어드는지 보는 것이다.
name: node-ci
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
with:
version: 9
- uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
cache-dependency-path: pnpm-lock.yaml
- run: pnpm install --frozen-lockfile
- run: pnpm test
체크리스트로 보는 설정 순서
캐시 설정은 한 번에 맞춘다고 생각하지 말고 반복 확인 항목으로 관리한다. 첫 번째 실행은 캐시가 없어서 오래 걸릴 수 있고, 두 번째 실행부터 효과가 보인다. 잠금 파일이 바뀐 직후에도 다시 내려받는 시간이 늘 수 있다. 그러므로 pull request마다 같은 시간을 기대하기보다, 변경 범위와 캐시 키가 맞게 반응하는지를 확인하는 관점이 필요하다.
- package.json의 packageManager 또는 팀 문서에서 pnpm 버전을 먼저 확인한다.
- workflow 파일에서 pnpm 준비 단계가 setup-node보다 앞에 있는지 본다.
- cache: pnpm과 cache-dependency-path가 현재 잠금 파일을 가리키는지 확인한다.
- pnpm install –frozen-lockfile로 잠금 파일과 실제 설치가 어긋나지 않게 한다.
- 첫 실행과 다음 실행의 install 단계 시간을 나눠 기록한다.
실패가 잦을 때 확인할 항목
캐시가 복원됐는데도 설치가 느리다면 pnpm store 경로, lockfile 변경 여부, Node 버전 차이, 액션 버전, 운영체제 매트릭스를 확인한다. 특히 ubuntu, windows, macOS를 함께 돌리는 매트릭스에서는 OS마다 캐시가 따로 관리되는 편이 자연스럽다. 하나의 캐시를 모든 환경에서 억지로 공유하려고 하면 오히려 빌드가 불안정해질 수 있다.
속도 측정과 팀 공유 방식
설정 전후를 비교할 때는 전체 워크플로 시간이 아니라 의존성 설치 단계 시간을 따로 본다. Actions 실행 화면에서 각 단계별 시간을 확인하고, 첫 실행과 다음 실행을 분리해 기록한다. 팀 문서에는 설정 파일의 위치, 캐시 기준 파일, pnpm 버전, 변경 시 확인할 명령을 짧게 남긴다. 이렇게 해 두면 새 저장소를 만들 때 같은 패턴을 복사해도 왜 필요한지 바로 이해할 수 있다.
최신 화면과 기능 변경 고지
GitHub Actions, setup-node, pnpm, Corepack의 화면 이름과 기본 동작은 버전 업데이트에 따라 달라질 수 있다. 이 글은 공식 문서의 일반 흐름을 기준으로 정리한 운영 체크리스트이며, 실제 적용 전에는 저장소의 Actions 탭, 액션 릴리스 노트, packageManager 필드, lockfile 위치를 다시 확인해야 한다. 유료 플랜 화면, 보관 기간, 실행 시간 제한 같은 운영 조건도 조직 설정에 따라 다를 수 있다.
설정 비교 표
| 항목 | 권장 기준 | 확인 이유 |
|---|---|---|
| pnpm 버전 | packageManager 또는 액션 입력값으로 고정 | 팀원과 CI의 설치 결과를 맞추기 위해 |
| Node 버전 | setup-node에서 명시 | 로컬과 Actions 실행 환경 차이를 줄이기 위해 |
| 캐시 기준 | pnpm-lock.yaml | 의존성 변경 때만 캐시가 새로 잡히게 하기 위해 |
| 설치 명령 | pnpm install –frozen-lockfile | 잠금 파일 기준 재현성을 지키기 위해 |
| 측정 방식 | install 단계 시간 비교 | 빌드나 테스트 시간과 분리해 효과를 보기 위해 |
FAQ
Q1. setup-node만 쓰면 pnpm 캐시가 자동으로 끝나나요?
기본 캐시는 도와주지만 프로젝트 구조에 따라 cache-dependency-path를 명시해야 한다. 특히 모노레포나 하위 앱 기준 실행에서는 잠금 파일 경로를 맞추는 것이 중요하다.
Q2. 첫 실행부터 빨라지지 않는 이유는 무엇인가요?
첫 실행은 저장된 캐시가 없어서 내려받기와 저장이 함께 일어난다. 보통 다음 실행부터 복원 효과를 확인할 수 있다.
Q3. pnpm/action-setup과 Corepack 중 무엇을 써야 하나요?
팀 표준에 맞추면 된다. packageManager 필드로 버전을 관리한다면 Corepack 흐름이 깔끔하고, 워크플로에서 명시적으로 버전을 보이게 하고 싶다면 pnpm/action-setup을 쓰기 쉽다.
Q4. 캐시를 켰는데도 시간이 거의 줄지 않으면 어떻게 하나요?
install 단계 로그에서 캐시 복원 여부, pnpm store 경로, lockfile 변경 여부, OS 매트릭스 차이를 확인한다. 테스트나 빌드가 느린 경우라면 캐시 설정만으로는 전체 시간이 크게 줄지 않을 수 있다.
Q5. 회사 저장소에 바로 적용해도 되나요?
먼저 별도 브랜치에서 install과 test만 대상으로 확인하고, 실행 시간과 로그를 팀에 공유한 뒤 배포 단계까지 넓히는 편이 안전하다.
운영 문서에 남길 짧은 템플릿
팀 문서에는 복잡한 설명보다 재사용 가능한 기준을 남기는 것이 좋다. 예를 들어 ‘이 저장소는 Node 20, pnpm 9, 루트 pnpm-lock.yaml을 기준으로 Actions 캐시를 사용한다. lockfile이 바뀌면 첫 실행은 느릴 수 있으며, install 단계가 다음 실행에서 줄어드는지 확인한다. 앱 폴더별 워크플로를 추가할 때는 working-directory와 cache-dependency-path를 함께 수정한다.’ 정도면 새 담당자도 핵심을 빠르게 파악할 수 있다. 또한 액션 버전을 바꿀 때는 변경 전후 실행 로그를 보존하고, 실패가 반복되면 캐시를 지우는 대신 버전과 경로부터 확인하도록 적어 두면 불필요한 원인 추적 시간을 줄일 수 있다.
