GitHub Actions cache-mode: 초록색 CI 뒤에 숨은 캐시 권한 확인하기
CI가 초록색으로 끝났는데 다음 실행에서 의존성을 다시 내려받는다면 캐시 키부터 고치기 쉽습니다. 이제는 권한 때문에 저장이 생략됐는지도 확인해야 합니다. 성공한 워크플로라는 사실만으로 캐시가 생성됐다고 판단할 수 없기 때문입니다.
GitHub는 2026년 9월 10일 cache-mode의 일반 제공을 발표했습니다. github.com의 모든 플랜에서 워크플로 또는 작업 단위로 캐시 접근을 정할 수 있습니다. 기존 읽기 전용 기본값을 다룬 이전 글에서 한 단계 나아가, 이번에는 명시적 설정과 검증 방법에 집중합니다.
확인된 기능: 복원과 저장의 네 조합
read는 복원만, write는 복원과 저장을 허용합니다. write-only는 저장만 허용하고 none은 둘 다 막습니다. write라는 이름을 저장 전용으로 오해하지 않는 것이 첫 번째 점검입니다.
작업에 선언한 값은 워크플로 전체 설정보다 우선합니다. 반면 재사용 워크플로 호출에서는 호출자가 허용한 수준보다 더 큰 접근 권한을 받을 수 없습니다. 한 파일의 선언만 읽고 전체 실행의 실제 권한을 판단하지 마세요.
초록색 실행도 저장 증거는 아니다
공식 문서는 허용되지 않은 캐시 작업이 안내 로그를 남기고 계속 진행된다고 설명합니다. 차단된 복원은 캐시 미스로 처리되고, 차단된 저장은 수행되지 않습니다. 워크플로 자체가 실패하지 않는다는 점이 관측의 핵심입니다.
따라서 운영 기록을 실행 성공 여부와 캐시 결과로 나눠 두는 편이 유용합니다. 어느 이벤트가 실행했는지, 어느 모드가 적용됐는지, 복원이 됐는지, 저장이 생략됐는지를 한 실행에서 확인하세요. 이것은 공식 기능 설명을 바탕으로 제안하는 운영 방식이며, 자동으로 제공되는 새 대시보드 기능은 아닙니다.
적용 전에 작은 권한표 만들기
저장소의 실제 워크플로를 펼쳐 캐시를 생산하는 작업과 소비하는 작업을 찾아보세요. 신뢰하는 브랜치에서 의존성을 준비하는 작업, 외부 변경을 시험하는 작업, 배포 산출물을 검증하는 작업을 같은 권한으로 묶을 필요는 없습니다.
각 작업에 대해 두 문장을 적습니다. 이 작업은 기존 캐시를 읽어야 하는가, 이 작업의 결과를 다음 실행이 읽도록 남겨도 되는가. 둘 다 필요하지 않다면 캐시를 붙이는 관성부터 다시 볼 수 있습니다. 단, 실제 설정은 저장소의 신뢰 경계와 빌드 구조에 맞춰 결정해야 합니다.
최소 실험: 읽기 전용 소비 작업
예를 들어 테스트용 워크플로에서 최상위에 cache-mode: read를 명시하고 작업별 재정의가 없는지 확인합니다. 캐시를 사용할 때의 테스트 결과와 캐시가 없는 상태의 테스트 결과가 같은지 비교합니다. 캐시는 실행 시간을 줄이는 보조 수단이어야 하므로, 캐시가 없다고 정확성이 달라지면 먼저 빌드 가정을 점검해야 합니다.
이 실험의 통과 기준은 CI 성공 한 줄이 아닙니다. 복원 시도와 저장 생략을 설명할 수 있고, 다음 실행에서 같은 입력으로 다시 검증할 수 있어야 합니다. 실험 전후 커밋, 트리거, 유효 설정과 로그 위치를 함께 남기면 다른 동료도 판단을 재현하기 쉽습니다.
재사용 워크플로는 호출 경로까지 읽기
공통 워크플로에 안전한 기본값을 넣었더라도 호출하는 쪽과 개별 작업 설정을 함께 검토해야 합니다. 저장소마다 같은 파일을 부른다는 사실과 같은 권한으로 실행된다는 사실은 같지 않습니다.
리뷰 시에는 호출자에서 시작해 작업의 캐시 선언, 호출된 워크플로 순서로 따라가 보세요. 예상한 권한과 실제 로그가 다르면 키를 더 복잡하게 만들기 전에 설정의 출처를 찾습니다. 이는 재사용이 많은 조직에서 진단 시간을 줄이기 위한 제안이며, 측정된 성능 개선 수치를 뜻하지 않습니다.
주의할 예외와 적용 순서
pull_request_target 같은 낮은 신뢰의 이벤트에 write 또는 write-only를 명시하면 읽기 전용 기본 제한을 덮어쓸 수 있고 캐시 오염 위험이 커집니다. GitHub는 이 경우 경고 주석을 추가합니다. 경고를 없애려고 쓰기 권한을 늘리는 식의 대응은 피해야 합니다.
반대로 모든 캐시를 막는 선택에도 비용이 있습니다. 다운로드와 빌드 시간이 늘 수 있으므로 대표 작업 하나에서 실행 시간을 직접 비교한 뒤 범위를 넓히세요. 숫자를 추정해 성능 효과를 약속하지 말고, 보안상 필요한 제한과 허용할 지연을 팀이 함께 정하는 편이 낫습니다.
팀이 지금 확인할 질문
오늘 할 일은 새 설정을 전 저장소에 일괄 추가하는 것이 아닙니다. 중요한 워크플로 하나에서 캐시 생산자와 소비자를 찾아 권한을 적고, 한 번의 실행에서 복원과 저장 근거를 확인하는 것입니다. 배포 작업이라면 담당자가 로그를 읽고 예상과 맞는지 검토할 수 있도록 변경을 작게 유지하세요.
실무에서 생길 수 있는 질문은 저장 단계가 생략됐는데 왜 CI는 성공했는가입니다. 이 글은 그러한 혼동을 공식 동작에 근거해 설명하며, 별도 커뮤니티 설문이나 보편적인 장애 발생률을 주장하지 않습니다. 새 기능을 도입할 때 성능 결과와 권한 결과를 각각 확인하면 다음 캐시 문제를 더 정확히 분류할 수 있습니다.