Gradle 캐시 최적화로 빌드 시간 단축하기

빌드가 5 분씩 걸리면 작은 수정 → PR → 리뷰까지 대기 시간이 눈덩이처럼 불어납니다. GitHub Actions에서 Gradle 캐시를 극대화해 “녹색 체크”를 더 빠르게 받아보세요.

 

1. 왜 CI 빌드가 느릴까?

GitHub Actions 러너는 매 실행마다 “새 서버”로 뜹니다.

• 의존성 다운로드 (~/.gradle/wrapper, ~/.gradle/caches)
• 컴파일 결과물 재생성
  이 두 가지가 시간을 잡아먹습니다. 캐시가 해답입니다.

2. 캐시의 두 얼굴

 

종류	역할	저장 위치	활성화 방법
Dependency Cache	라이브러리 ZIP·JAR 다운로드 결과	~/.gradle/wrapper, ~/.gradle/caches/modules-*	actions/cache 또는 setup-gradle
Build Cache	Task 출력물(클래스파일 등)	~/.gradle/caches/build-cache-1	org.gradle.caching=true

 

표 대신 간단 요약: “라이브러리 캐시”와 “Task 결과 캐시” 두 겹으로 가속한다.

3. actions/cache 기본 예제

- name: Cache Gradle
  uses: actions/cache@v4
  with:
    path: |
      ~/.gradle/caches
      ~/.gradle/wrapper
    key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
    restore-keys: ${{ runner.os }}-gradle-

• key: OS + Gradle 스크립트 해시 → 의존성 변경 시 자동 무효화
• restore-keys: 근사치 키로 과거 캐시 재사용

4. 더 똑똑하게: setup-gradle@v3

- name: Setup Gradle
  uses: gradle/actions/setup-gradle@v3
  with:
    gradle-version: wrapper          # wrapper에 정의된 버전 사용
    cache-read-only: ${{ github.ref != 'refs/heads/develop' }}

• 의존성·래퍼·빌드 스캔까지 한 번에 관리
• cache-read-only로 PR에서 캐시 오염 막기

5. Gradle Build Cache ON

gradle.properties에 한 줄:

org.gradle.caching=true

동일 입력의 Task는 재실행 없이 결과만 복사합니다. 사내 Gradle Enterprise 또는 Build Cache Node를 연결하면 팀 전체가 캐시를 공유할 수 있습니다.

6. 캐시 키 설계 3 원칙

1. “무효화 용이성 > 적중률” – 오래된 바이너리 오류를 막는다.
2. OS·JDK 버전을 포함 – 런타임 불일치 방지.
3. 대형 멀티 모듈은 모듈별 캐시 or restore-keys로 유연성 확보.

7. 효과 측정 & 관리

• 의존성 캐시만으로 78 초 → 47 초(-40 %) 단축.
• GitHub Free 요금제 기준 캐시 보존: 7 일 / 10 GB. 주기적으로 키를 바꿔 “고인 물” 제거.

8. 흔한 오류 Top 3

1. 경로 오타 – ~/.gradle 앞에 틸드 빠짐.
2. 동일 Job에서 캐시 두 번 저장 – 마지막만 유효; conflict 발생.
3. Gradle Build Dir 캐싱 – 효용 ↓·사이즈 ↑. Task Output Cache로 대체하세요.