GitLab CI/CD 캐시, 왜 내 코드가 안 바뀔까?

GitLab CI/CD를 사용할 때, 캐시(cache) 정책 설정이 제대로 되어 있지 않으면 코드 변경이 제대로 반영되지 않는 문제가 발생할 수 있습니다. (나도 가끔 겪었는데 👀) policy: pull 설정 때문에 기존 캐시가 유지되면서 새로운 코드가 반영되지 않는 일이 있습니다.

이번 글에서는 GitLab CI/CD의 캐시 개념과 policy 설정의 차이를 살펴보고, 내가 겪었던 문제를 정리해보려고 합니다!

 

🗒️ GitLab CI/CD cache란?

GitLab CI/CD에서 캐시(cache)는 빌드 테스트 속도를 향상시키기 위해 특정 파일이나 디렉터리를 저장하는 기능입니다.

캐시는 다음 실행에서 다시 사용될 수 있어 다운로드 시간을 줄이는 데 도움이 됩니다!

✅ 캐시와 아티팩트의 차이

구분	Cache	Artifacts
저장 범위	브랜치 내에서만 공유	전체 파이프라인에서 공유
저장 위치	특정 Runner에 저장	GitLab 서버에 저장
보존 기간	기본적으로 자동 삭제	expire_in으로 설정 가능
사용 목적	빌드 속도 개선	빌드 결과물 보관

 

캐시는 특정 Runner에 저장되기 때문에 다른 Runner에서 실행될 경우 사용되지 않을 수 있습니다.

 

📖 GitLab CI/CD Cache 정책 (policy)

GitLab의 cache는 policy 설정에 따라 동작 방식이 달라집니다.

✅ policy 설정값과 차이

policy 값	동작 방식	특징
pull (기본값)	기존 캐시를 가져와 사용하지만 업데이트는 안 함	캐시 활용 가능하지만, 변경 사항이 반영되지 않을 수 있음
push	새로운 캐시를 생성하여 저장	항상 최신 상태를 유지하지만, 매번 새로 저장하므로 속도 저하 가능
pull-push	기존 캐시를 불러오고 변경된 내용은 다시 저장	캐시 활용과 업데이트를 동시에 수행하여 효율적

 

📑 policy: pull로 인해 코드 변경이 반영되지 않는 문제

🔍 문제 원인

• CI/CD 실행 시 코드 자체는 항상 최신으로 체크아웃(Git pull)됨.
• 하지만 캐시된 파일(예: 빌드 결과물, 패키지)이 그대로 유지되면서 이전 실행 결과가 적용됨.
• 빌드 과정에서 변경된 코드가 반영되지 않고, 이전 캐시된 파일이 계속 사용됨.

🚨 예제: node_modules 캐시 문제

❌ policy: pull (변경 사항 반영되지 않음)

cache:
  key: my-cache
  paths:
    - node_modules/
  policy: pull

• package.json이 변경되어도 node_modules/가 그대로 유지됨.
• 새로운 패키지가 반영되지 않고 이전 캐시를 계속 사용.

✅ policy: pull-push (변경 사항 반영)

cache:
  key: "$CI_COMMIT_REF_SLUG-$(checksum package-lock.json)"
  paths:
    - node_modules/
  policy: pull-push

• package-lock.json이 변경되면 새로운 캐시가 생성됨.
• 변경 사항을 반영하면서 기존 캐시도 재활용 가능.

 

GitLab Cache 최적화 방법

Cache 정책을 조정하는 것 외에도 빌드 속도를 최적화할 방법이 있습니다!

🚀 해결 방법 1: policy: pull-push 활용

• 기존 캐시를 활용하면서 변경 사항만 업데이트할 수 있도록 설정.
• 필요할 때만 새로운 캐시를 생성해 CI/CD 속도를 최적화.

🚀 해결 방법 2: 캐시 키(key) 설정 최적화

cache:
  key: "$CI_COMMIT_REF_SLUG-$(checksum package-lock.json)"
  paths:
    - node_modules/
  policy: pull-push

• package-lock.json이 변경될 때만 새로운 캐시를 생성하여 불필요한 캐시 업데이트 방지.

🚀 해결 방법 3: 브랜치 간 캐시 공유

cache:
  key: shared
  paths:
    - node_modules/
  policy: pull-push

• 같은 프로젝트 내에서 캐시를 공유하여 반복 다운로드 시간을 줄임.

🚀 해결 방법 4: 외부 저장소(S3 등) 활용

(이 방법은 일반적으로 사용되는 방식이지만, 직접 적용해보진 않았기에 개념 정도만 정리했다.)

• GitLab Runner의 캐시 저장소 대신 AWS S3 같은 외부 저장소를 활용하면 지속적인 캐시 활용이 가능.

 

 

💡
policy: pull을 사용하면 이전 캐시를 유지하지만 변경 사항이 반영되지 않을 수 있음.
policy: push로 설정하면 새로운 캐시를 생성하면서 코드 변경이 반영되지만 CI/CD 속도가 느려질 수 있음. 가장 효율적인 방식은 policy: pull-push와 key 설정을 활용하여 캐시를 최적화하는 것!
GitLab CI/CD를 사용할 때, 적절한 캐시 정책을 설정하면 코드 반영 문제를 해결하면서도 빌드 속도를 최적화할 수 있다.
프로젝트의 빌드 환경에 따라 최적의 설정을 적용해보면 좋을 것 같습니다!