기술 · 실용 가이드
GitHub Actions 캐시가 복원되지 않을 때: 키·버전·참조 범위·접근 모드 비교
캐시 항목이 존재해도 현재 실행이 읽을 수 있는 것은 아닙니다. 캐시 삭제나 러너 변경 전에 캐시를 만든 실행과 읽지 못한 실행을 비교하세요.
GitHub Actions의 캐시 미스만으로 저장 실패, 러너 고장 또는 키 변경을 단정할 수 없습니다. 캐시 버전, 브랜치나 PR 참조 범위, 복원 키 검색 순서, 접근 모드와 항목의 현재 존재 여부도 결과에 영향을 줍니다.
먼저 캐시를 만든 실행과 복원에 실패한 실행의 비교 기록을 만듭니다. 계산된 키, 경로와 압축 입력, 실제 참조, 이벤트, 저장소, 권한, 조회 결과와 저장 결과를 나란히 확인합니다.
정확한 일치 실패, 부분 복원, PR 범위 격리, 삭제된 항목을 구분해야 합니다. 키를 바꾸거나 캐시를 지우고 권한을 늘리거나 러너를 옮기기 전에 증거를 보존합니다.
캐시 생성 실행과 소비 실행의 비교 기록
성공적으로 저장한 실행 하나와 이를 재사용해야 했던 실행 하나를 선택합니다. 저장소, 워크플로 파일과 커밋, 이벤트, github.ref, github.ref_name, 해당되는 base 및 head 참조, 러너 OS와 아키텍처, action 버전, 계산된 주 키, 모든 복원 키, 경로, lookup-only, fail-on-cache-miss와 최종 복원·저장 로그를 양쪽에서 기록합니다.
YAML 템플릿만 비교하지 마세요. push, pull_request, 행렬 작업과 재사용 워크플로에서 식의 결과가 달라질 수 있습니다. 로그나 안전한 진단 단계에서 실제 값을 확인하되 토큰, 환경 비밀, 자격 증명이나 비공개 파일 내용은 출력하지 않습니다.
눈에 보이는 키와 캐시 버전을 구분
캐시 버전에는 경로와 압축 도구 관련 메타데이터가 반영됩니다. 같은 키를 표시해도 경로 입력, 플랫폼, 압축 환경이나 action 구현 차이로 호환되지 않는 버전이 만들어질 수 있습니다.
식 계산 후 경로 입력의 순서, 와일드카드, 물결표, 작업 공간과 OS 차이를 비교하고 러너 이미지와 action 버전도 남깁니다. 키에 타임스탬프를 붙여 문제를 덮으면 새 항목만 늘어나 원래 증거를 비교하기 어려워집니다.
참조 범위를 가시성 규칙으로 이해
pull_request 실행에서 만든 캐시는 PR 병합 참조에 속합니다. 같은 PR을 재실행할 때 쓸 수 있지만 대상 브랜치나 다른 PR은 복원할 수 없습니다. 현재 브랜치와 허용된 기본 브랜치 캐시를 사용할 수 있어도 임의의 하위·형제 브랜치 캐시까지 읽는 것은 아닙니다.
두 실행의 이벤트와 실제 참조를 기록합니다. 같은 키가 push에서는 맞고 pull_request에서는 실패하면 러너나 경로보다 범위를 먼저 비교하세요. 커뮤니티 질문은 증상 보고일 뿐 원인의 증명이 아닙니다. 실제 참조를 GitHub 공식 접근 규칙과 대조해야 합니다.
cache-hit와 실제 복원 결과를 함께 확인
주 키가 정확히 일치할 때만 cache-hit가 true입니다. 주 키가 없지만 복원 키의 접두사로 부분 일치하면 false여도 데이터는 복원될 수 있습니다. false를 무조건 복원 데이터 없음으로 처리하면 불필요한 작업을 반복하게 됩니다.
복원 로그, 일치한 키, 원래 출력 문자열을 함께 남깁니다. README의 Outputs 항목은 미스 출력을 빈 문자열로 설명하므로 모든 비 true 값을 false로 합치지 마세요. 로그와 함께 정확한 일치, 부분 복원, 데이터 미복원을 구분합니다. 부분 복원 후에도 변경된 의존성을 반영하기 위한 설치가 필요할 수 있습니다. Stack Overflow 질문자는 조건의 따옴표 없는 불리언 true를 문자열 'true' 비교로 바꾼 뒤 해결됐다고 보고했습니다. 이는 해당 워크플로의 보고이며 모든 캐시 미스의 원인을 입증하지는 않습니다.
접근 모드를 별도로 점검
실제 ACTIONS_CACHE_MODE, 워크플로 및 job의 cache-mode, 재사용 워크플로 제한과 작업 생략 로그를 기록합니다. read는 복원만, write는 복원과 저장, write-only는 저장만 허용하며 none은 둘 다 막습니다. 읽기 금지로 복원을 건너뛰어도 미스로 표시될 수 있으므로 항목 부재를 단정하면 안 됩니다.
모든 PR에 같은 제한이 적용된다고 보지 마세요. 기본 브랜치의 낮은 신뢰 트리거 제한과 pull_request의 병합 참조 격리는 별개입니다. 저장소·이벤트·참조·유효 모드를 함께 확인합니다. 성공한 작업에도 저장 거부나 생략이 있을 수 있습니다. 경고를 보존하고 안전한 기본값을 유지하며 적절한 신뢰 실행이 캐시를 만들도록 하세요.
항목이 지금도 존재하는지 입증
과거 저장 성공은 당시의 존재만 입증합니다. 저장 한도, 미사용 보존 기간, 수동 삭제와 빈번한 캐시 교체에 따른 제거를 확인하세요. 권한 있는 계정으로 캐시 목록이나 API를 조회해 키, 참조, 생성 시간, 최근 접근 시간과 크기를 점검합니다.
진단을 위해 모든 캐시를 삭제하지 마세요. 항목이 없다면 생성 로그와 조회 결과를 보존하고 통제된 재생성을 한 번 수행합니다. 다른 참조나 비호환 버전에 존재한다면 삭제해도 가시성 규칙은 달라지지 않고 증거만 없어집니다.
결과에 맞는 최소 변경 하나를 선택
같은 키에서 미스가 나면 읽기 허용 여부를 먼저 확인한 뒤 버전과 참조를 비교합니다. 부분 복원은 후속 조건을 점검하면서 필요한 의존성 동기화는 유지합니다. PR 범위 문제라면 적절한 신뢰 생성 실행을 사용하거나 격리를 받아들입니다. 항목 부재라면 한 번 생성해 목록을 확인하고, 미스를 없애려고 비신뢰 접근을 확대하지 않습니다.
식별 조건이 모두 같고 예상 참조에서 항목이 보인다면 비교 기록을 첨부해 문제를 제기합니다. 실행 URL, 안전한 계산 값, action 버전, 러너 이미지, 목록 증거와 최소 재현 워크플로는 증거 삭제나 비밀 공개 없이 결함을 조사하는 데 도움이 됩니다.
