GitHub Actions 캐시 전략: CI/CD 파이프라인을 5배 빠르게 만드는 법

npm install에 3분 15초.

지난해 제가 맡았던 한 프로젝트의 CI 빌드 시간이었습니다. 코드를 푸시할 때마다 GitHub Actions 로그의 로딩 표시를 바라보며 초록색 체크 표시가 나타나기만 기다려야 했습니다. 솔직히 그때는 다른 창으로 넘어가 딴짓을 하곤 했습니다. 어차피 기다려야 했으니까요.

그 후 캐시를 추가하자 같은 빌드가 40초 만에 끝났습니다. 거의 5배 빨라진 셈입니다.

마법 같은 일은 아닙니다. GitHub Actions의 캐시 전략을 제대로 설정했을 뿐입니다. 이 글에서는 제가 겪은 시행착오와 직접 테스트한 데이터, 바로 복사해서 사용할 수 있는 설정 템플릿을 한데 정리합니다. CI 빌드를 기다리고 있다면 커피 몇 잔 마실 시간을 아낄 수 있을 겁니다.

1. 캐시 메커니즘의 핵심 개념

먼저 캐시가 어떻게 작동하는지 이해해야 합니다. 그렇지 않으면 설정 과정에서 실수하기 쉽습니다.

GitHub Actions의 캐시 메커니즘은 사실 간단합니다. 검색 → 복원 → 저장의 세 단계입니다. key를 정의하면 GitHub가 모든 캐시에서 일치하는 항목을 찾습니다. 찾으면 작업 디렉터리에 바로 복원하고, 찾지 못하면 작업이 끝난 뒤 새 캐시를 저장합니다.

다만 반드시 알아야 할 제한이 몇 가지 있습니다.

10GB 제한에 걸린 사례를 본 적이 있습니다. 프로젝트 의존성이 너무 많아 캐시가 계속 커지다가 결국 새 캐시는 저장되지 않고 기존 캐시마저 정리되어, 빌드할 때마다 콜드 스타트가 발생했습니다.

또 하나 혼동하기 쉬운 점이 있습니다. Cache와 Artifact는 서로 다릅니다. Cache는 CI를 빠르게 하기 위한 것이고, Artifact는 빌드 결과물이나 테스트 보고서처럼 사람이 확인하고 장기간 보관할 파일을 위한 것입니다. Cache에는 10GB 제한이 있지만 Artifact에는 상한이 없습니다. 다만 저장소 스토리지를 사용합니다.

이 밖에 Docker Layer Cache도 있습니다. Docker 빌드 전용 캐시로, 일반 캐시와는 작동 방식이 조금 다릅니다. 뒤에서 별도로 살펴보겠습니다.

2. 캐시 키 설계 전략

캐시의 적중 여부는 key를 어떻게 설계하느냐에 달려 있습니다. 캐시 전략 전체에서 가장 중요한 부분입니다.

hashFiles()란 무엇인가요?

GitHub는 파일의 해시값을 계산하는 내장 함수 hashFiles()를 제공합니다. 보통 package-lock.json이나 yarn.lock에 사용합니다. 의존성이 바뀌지 않으면 해시도 그대로이므로 캐시를 적중시킬 수 있습니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

key: npm-{{ runner.os }}-{{ hashFiles('**/package-lock.json') }}

이 코드는 npm-Linux-a1b2c3d4e5f6... 같은 형태의 키를 생성합니다. package-lock.json이 바뀌지 않는 한 이 키도 바뀌지 않습니다.

restore-keys: 예비 방식

하지만 의존성은 언젠가 업데이트됩니다. 이때 restore-keys가 필요합니다. 일종의 폴백 매칭 메커니즘입니다.

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-{{ runner.os }}-{{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      npm-{{ runner.os }}-

먼저 전체 key가 일치하는지 확인합니다. 일치하는 캐시가 없으면 npm-Linux-로 시작하는 기존 캐시를 찾습니다. 정확히 일치하지 않더라도 node_modules에 필요한 패키지 대부분이 이미 있으므로 새 의존성만 증분 설치하면 됩니다.

세 가지 키 명명 패턴 비교

직접 테스트한 결과 다음 세 가지 패턴을 권장합니다.

간단한 패턴(소규모 프로젝트에 적합):

key: {{ runner.os }}-node-{{ hashFiles('**/package-lock.json') }}

버전 패턴(여러 Node 버전에 적합):

key: {{ runner.os }}-node{{ matrix.node-version }}-{{ hashFiles('**/package-lock.json') }}

다중 경로 패턴(monorepo에 적합):

key: {{ runner.os }}-{{ hashFiles('**/package-lock.json', '**/yarn.lock') }}

캐시 적중 여부 확인 방법

actions/cache는 cache-hit 변수를 출력합니다.

- uses: actions/cache@v4
  id: cache-npm
  with:
    path: ~/.npm
    key: {{ runner.os }}-node-{{ hashFiles('**/package-lock.json') }}

- name: Check cache hit
  run: echo "Cache hit - {{ steps.cache-npm.outputs.cache-hit }}"

true는 정확히 일치했음을 뜻하고, false는 부분 일치 또는 완전한 miss를 뜻합니다. 이 변수에 따라 npm ci를 실행할지 결정할 수 있습니다.

- name: Install dependencies
  if: steps.cache-npm.outputs.cache-hit != 'true'
  run: npm ci

3. 실전 설정 예시

이론은 여기까지입니다. 이제 바로 코드를 살펴보겠습니다. 아래 설정은 모두 직접 테스트했으며 그대로 복사해 사용할 수 있습니다.

npm 캐시(setup-node 권장)

setup-node에는 이미 캐시 기능이 내장되어 있어 actions/cache를 직접 사용하는 것보다 간결합니다.

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # 또는 'yarn', 'pnpm'

한 줄 설정이면 충분합니다. 다만 node_modules처럼 다른 디렉터리를 캐시하려면 여전히 actions/cache를 사용해야 합니다.

- uses: actions/cache@v4
  with:
    path: node_modules
    key: {{ runner.os }}-nm-{{ hashFiles('**/package-lock.json') }}
    restore-keys: {{ runner.os }}-nm-

제 권장 사항: 특별한 요구 사항이 없다면 setup-node의 내장 캐시를 우선 사용하세요.

yarn과 pnpm

yarn의 캐시 디렉터리는 npm과 다릅니다.

- uses: actions/cache@v4
  with:
    path: |
      ~/.yarn/cache
      ~/.yarn/install-state.gz
    key: yarn-{{ runner.os }}-{{ hashFiles('**/yarn.lock') }}

pnpm은 조금 더 특수하며 전역 store를 사용합니다.

- uses: pnpm/action-setup@v4
  with:
    version: 9

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

Python/pip 캐시

Python 프로젝트의 캐시 경로는 다음과 같습니다.

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-{{ runner.os }}-{{ hashFiles('**/requirements.txt') }}
    restore-keys: pip-{{ runner.os }}-

Docker Layer Cache

Docker 빌드는 가장 많은 시간이 걸리는 작업 중 하나입니다. 다행히 BuildKit은 GitHub Actions 캐시 백엔드를 지원합니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

- uses: docker/setup-buildx-action@v3

- uses: docker/build-push-action@v6
  with:
    context: .
    push: false
    cache-from: type=gha
    cache-to: type=gha,mode=max

type=gha는 GitHub Actions의 캐시 서비스에 Docker 레이어를 저장한다는 뜻입니다. 직접 테스트해 보니 5분 걸리던 이미지 빌드가 약 1분으로 줄었습니다.

Go 모듈 캐시

- uses: actions/cache@v4
  with:
    path: |
      ~/go/pkg/mod
      ~/.cache/go-build
    key: go-{{ runner.os }}-{{ hashFiles('**/go.sum') }}

Rust Cargo 캐시

- uses: actions/cache@v4
  with:
    path: |
      ~/.cargo/registry
      ~/.cargo/git
      target
    key: cargo-{{ runner.os }}-{{ hashFiles('**/Cargo.lock') }}

Rust는 컴파일 시간이 길어 캐시로 많은 시간을 절약할 수 있습니다. 다만 target 디렉터리가 계속 커질 수 있으므로 정기적으로 정리하는 것이 좋습니다.

4. 성능 최적화와 모범 사례

직접 측정한 데이터와 경험한 문제를 정리했습니다. 같은 시행착오를 줄이는 데 도움이 되길 바랍니다.

성능 벤치마크 데이터

RunsOn의 테스트 보고서(2026년 1월 업데이트)에 따르면 캐시를 적절히 설정했을 때 다음과 같은 결과가 나왔습니다.

캐시 적중률은 70~90%이며, 키 전략을 얼마나 잘 설계했는지에 따라 달라집니다.

흔한 실수

node_modules를 직접 캐시하지 마세요

처음에는 저도 그렇게 했다가 큰 문제를 겪었습니다.

# 이렇게 작성하지 마세요
path: node_modules

node_modules는 플랫폼에 따라 달라집니다. Linux에서 설치한 패키지는 Windows에서 실행할 때 문제가 생길 수 있습니다. 올바른 방법은 전역 캐시 디렉터리(~/.npm)를 캐시하고 npm ci가 직접 구성하도록 하는 것입니다.

OS 간 캐시에는 GNU tar + zstd를 사용하세요

기본 tar 형식은 macOS와 Windows에서 서로 달라 캐시 복원에 실패할 수 있습니다. 다음 설정을 추가하세요.

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-{{ runner.os }}-{{ hashFiles('**/package-lock.json') }}
    enableCrossOsArchive: true

캐시 오염 문제

캐시에 문제가 있는 의존성이 저장되어 빌드가 계속 실패할 때가 있습니다. 해결 방법은 다음과 같습니다.

1. 캐시 수동 삭제: GitHub 저장소의 Actions → Caches 페이지에서 삭제합니다.
2. key 강제 변경: key에 접두사나 타임스탬프를 추가해 새로 생성합니다.

key: npm-v2-{{ runner.os }}-{{ hashFiles('**/package-lock.json') }}

모범 사례 체크리스트

마지막으로 핵심 사항을 정리합니다. 설정하기 전에 하나씩 확인해 보세요.

1. 공식 action의 내장 캐시를 우선 사용하세요(setup-node, setup-python).
2. key에 hashFiles를 포함하세요. 그렇지 않으면 의존성이 업데이트된 뒤에도 오래된 캐시를 사용하게 됩니다.
3. restore-keys를 작성하세요. 폴백 매칭이 위기 상황에서 도움이 됩니다.
4. node_modules를 캐시하지 말고 전역 디렉터리를 캐시하세요.
5. 오래된 캐시를 정기적으로 정리해 10GB 제한을 넘지 않도록 하세요.

5. 자주 묻는 질문

Q1: 캐시 적중률이 낮은 이유는 무엇인가요?

가장 흔한 원인은 key가 너무 자주 바뀌는 것입니다. 예를 들어 key에 타임스탬프나 브랜치 이름을 넣으면 push할 때마다 새로운 key가 생성됩니다. 해결 방법은 불필요한 변수를 빼고 runner.os와 hashFiles만 사용하는 것입니다.

또 다른 원인은 hashFiles가 매칭하지 않아야 할 파일까지 매칭하는 것입니다. 예를 들어 hashFiles('**/*.json')라고 작성하면 설정 파일 하나만 바뀌어도 캐시가 무효화됩니다. package-lock.json이나 yarn.lock만 매칭하도록 변경하세요.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

Q2: 캐시 공간 한도를 초과하면 어떻게 해야 하나요?

10GB가 넉넉해 보여도 monorepo나 Docker 캐시는 쉽게 한도를 넘을 수 있습니다. 해결 방법은 다음과 같습니다.

1. 정기 정리: GitHub Actions → Caches에서 오래된 캐시를 수동으로 삭제합니다.
2. 캐시 분리: 의존성 유형마다 다른 key를 사용해 하나의 캐시에 모든 것을 저장하지 않습니다.
3. self-hosted runners 사용: 10GB 제한이 없습니다.

Q3: self-hosted runners에는 특별한 설정이 필요한가요?

특별한 설정은 필요하지 않으며 캐시 메커니즘도 같습니다. 다만 self-hosted runners에는 캐시가 로컬에 저장되어 네트워크 전송 지연 없이 더 빠르게 복원된다는 장점이 있습니다. 단점은 캐시가 자동으로 정리되지 않아 정기적으로 삭제하는 스크립트를 직접 작성해야 한다는 것입니다.

Q4: 캐시를 강제로 업데이트하려면 어떻게 하나요?

key를 변경하세요. 접두사에 버전 번호를 추가하면 됩니다.

key: npm-v3-{{ runner.os }}-{{ hashFiles('**/package-lock.json') }}

또는 기존 캐시를 삭제해 시스템이 새로 생성하도록 할 수 있습니다.

마무리

지금까지의 내용을 한 문장으로 요약하면 이렇습니다. 캐시를 잘 활용하면 CI를 5배 빠르게 만들 수 있습니다.

간단히 계산해 보겠습니다. 빌드할 때마다 2분을 절약하고 하루에 10번 실행한다면 한 달에 600분, 약 10시간을 아끼는 셈입니다. 글을 여러 편 쓸 수 있는 시간입니다.

GitHub Actions를 이제 막 시작했다면 setup-node의 내장 캐시부터 사용해 보세요. 설정 한 줄이면 충분합니다. 병목이 생겼을 때 더 복잡한 키 전략과 Docker Layer Cache를 살펴봐도 늦지 않습니다.

참고로 이 글은 GitHub Actions 실전 가이드 시리즈의 세 번째 글입니다. 앞서 CI 파이프라인 구축과 배포 전략도 다뤘으니 관심이 있다면 이전 글도 확인해 보세요.

다음에 코드를 푸시할 때는 빌드 시간을 꼭 살펴보세요. 3분을 40초로 줄일 수 있는지 직접 시험해 보면 알 수 있습니다.