# GitHub Actions 캐시 용량 한도: 캐시가 밀려나고, 복원이 느리고, 빗나가는 이유

> GitHub의 Actions 캐시는 리포지토리당 10 GB를 담고, 그것을 넘으면 가장 오래전에 읽은 항목부터 지우고, 7일 동안 쓰지 않은 항목은 버려요. 캐시가 맞아도 새 VM으로의 다운로드예요. 해결책마다 드는 비용, 그리고 디스크를 유지하는 실행기라면 캐시 대부분이 필요 없는 이유를 정리했어요. 월 $39 정액이에요.

GitHub Actions는 리포지토리마다 10 GB의 캐시를 줘요. 리포지토리가 그것을 넘으면 GitHub는 새 항목을 저장한 뒤, 한도 아래로 돌아올 때까지 가장 오래전에 읽은 항목부터 지우고, 7일 동안 어떤 작업도 읽지 않은 항목도 지워요. 브랜치는 자기 캐시와 기본 브랜치의 캐시만 읽으므로, 새 브랜치의 첫 실행은 자주 빗나가요. 그리고 캐시가 맞아도 다운로드예요. GitHub 호스팅 실행기의 작업은 매번 새 VM에서 시작하니, 아카이브를 다시 받아서 풀어요. 한도를 올릴 수는 있고(10 GB를 넘으면 GB당 월 $0.07), 키를 다듬을 수도 있지만, 다운로드는 그대로예요.

Skipbox는 다운로드를 없애요. 작업은 작업 사이에도 유지되는 내 계정 전용 머신에서 돌므로, npm, pnpm, Gradle, Go, Cargo 캐시와 Docker 레이어가 지난 작업에서 디스크에 그대로 있어요(S는 80 GB, GitHub 실행기는 14 GB). actions/cache가 저장한 것은 머신 옆에 남으므로, 복원은 로컬 읽기예요. `runs-on: skipbox` 한 줄만 바꾸면 월 $39 정액에 실행 시간 무제한이에요.

- GitHub: 리포지토리당 10 GB, 7일 동안 안 쓴 항목은 삭제, 맞아도 매번 다시 다운로드
- Skipbox: 패키지 캐시와 Docker 레이어가 내 머신의 디스크에 남고, 캐시 공간은 GitHub의 7배 이상
- 4 vCPU로 월 20,000분: GitHub에서 $222, Skipbox에서 $39

**GitHub Actions를 정액으로, 실행 시간 무제한** Skipbox는 GitHub Actions 작업을 나만 쓰는 전용 머신에서 돌려요. 몇 분을 돌리든 가격은 월 $39 그대로예요. Docker 레이어와 의존성 캐시가 작업 사이에도 남아서 다음 작업이 바로 시작돼요.

4 vCPU 실행기, 매달 20,000분: GitHub $222 → Skipbox $39. 매달 $183 절약.

옮기는 데는 한 줄이면 돼요: `runs-on: skipbox`.

[7일 무료 체험 시작하기](https://app.skipbox.dev/sign-in?ref=g-github-actions-cache-size-limit-ko)

## GitHub의 캐시 규칙

GitHub의 [의존성 캐싱 문서](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching), [Actions 청구](https://docs.github.com/en/billing/concepts/product-billing/github-actions), 그리고 [10 GB를 넘는 캐시](https://github.blog/changelog/2025-11-20-github-actions-cache-size-can-now-exceed-10-gb-per-repository/)에 관한 변경 기록에 따르면:

| 규칙 | GitHub가 하는 일 |
|---|---|
| 용량 | 기본은 리포지토리당 10 GB, 모든 브랜치와 워크플로가 함께 써요 |
| 용량을 넘으면 | 새 항목을 저장한 뒤, 리포지토리가 한도 아래가 될 때까지 마지막으로 읽은 시점이 오래된 항목부터 지워요. 정리는 1시간마다 돌아요 |
| 안 쓰는 항목 | 7일 넘게 읽지 않은 항목은 지워요 |
| 더 큰 한도 | Pro, Team, Enterprise 계정에서는 관리자가 용량과 일수를 늘릴 수 있어요. 10 GB를 넘으면 시간마다의 최대치로 GB당 월 $0.07이에요. 예산에 닿으면 다음 청구 주기까지 캐시가 읽기 전용이 돼요 |
| 브랜치 | 실행은 자기 브랜치와 기본 브랜치의 캐시를, 풀 리퀘스트의 실행은 베이스 브랜치의 캐시도 복원해요. 형제나 자식 브랜치의 캐시는 절대 못 읽어요 |
| 풀 리퀘스트 | 풀 리퀘스트의 캐시는 병합 ref 범위라서, 그 풀 리퀘스트의 다시 실행만 읽어요 |
| 항목 | 바꿀 수 없어요. 이미 있는 키는 다시 저장되지 않아요 |
| 적중 | `cache-hit`은 `key`와 정확히 일치할 때만 `true`예요. `restore-keys`로 맞으면 `false`예요 |
| 속도 | 리포지토리당 1분에 업로드 200번, 다운로드 1,500번까지 |

## 캐시가 밀려나는 이유

리포지토리가 저장하는 모든 것을 10 GB 하나가 담아요. 브랜치와 풀 리퀘스트마다 자기 항목을 저장해요. Node 버전 셋, OS 둘의 행렬이면 여섯 개를 저장해요. Docker의 `type=gha` 빌드 캐시도 같은 10 GB에 들어가요. 하루의 저장량이 한도를 넘으면, 새로 저장할 때마다 오래된 항목이 지워지고, 그게 다음 작업에 필요한 항목인 경우가 많아요. GitHub는 이것을 캐시 스래싱이라고 불러요.

무엇이 채우고 있는지 보려면 항목을 크기순으로 나열하세요.

```bash
gh cache list --sort size_in_bytes --limit 20
```

리포지토리의 Actions › Caches 페이지에도 항목마다 브랜치와 마지막 사용 시점이 같이 나와요.

## 복원이 느린 이유

GitHub 호스팅 실행기에서 캐시 적중은 새 VM으로의 다운로드와 풀기예요. 시간은 아카이브 크기에 따라 늘어나므로, 몇 GB로 커진 캐시는 건너뛰려던 설치만큼 오래 걸릴 수 있어요. 멈춘 다운로드는 actions/cache의 세그먼트 타임아웃(기본 10분, `SEGMENT_DOWNLOAD_TIMEOUT_MINS`)에서 끊겨요.

대부분의 설정은 생각보다 적게 복원해요. [setup-node](https://github.com/actions/setup-node)의 `cache:` 입력은 `node_modules`가 아니라 패키지 관리자의 다운로드 캐시를 저장해요. 복원 뒤에도 `npm ci`가 모든 패키지를 설치해요. setup-python의 pip 캐시도 같아요. 다운로드는 돌아오지만, 환경은 다시 설치해요.

## 캐시가 빗나가는 이유

- **키가 바뀌었어요.** `hashFiles('**/package-lock.json')`이 든 키는 잠금 파일이 바뀔 때마다 빗나가요. `restore-keys`로 부분 일치를 얻을 수 있지만, 그러면 `cache-hit`은 `false`예요.
- **새 브랜치예요.** 기본 브랜치의 캐시는 읽어도, 다른 기능 브랜치의 캐시는 못 읽어요. 기본 브랜치에서 워크플로가 한 번도 안 돌았다면 읽을 것이 없어요.
- **밀려났어요.** 한도나 7일 규칙이 가져갔어요.
- **저장된 적이 없어요.** 항목은 바꿀 수 없으므로, 있는 키는 다시 저장되지 않고, 캐시 내용은 첫 저장 때만큼 낡은 채로 남아요. 포크에서 온 풀 리퀘스트는 아예 저장하지 못할 수도 있어요.

**같은 실행의 다음 작업에 파일을 넘기는 건** 다른 도구예요. 캐시는 다음 실행을 위한 것이고, 같은 워크플로의 뒤 작업이 필요로 하는 빌드 결과는 `actions/upload-artifact`와 `actions/download-artifact`로 넘겨요. 아티팩트는 10 GB와 따로 저장 공간이 있고, 이것도 새 VM으로의 다운로드예요.

## GitHub 실행기에서 해결책마다 드는 비용

- **한도를 올리기.** 밀려나는 일은 줄지만, Pro, Team, Enterprise 계정에서 10 GB를 넘는 만큼 GB당 월 $0.07을 내요(GitHub의 예: 200 GB를 꽉 채우면 월 $13.30). 복원은 여전히 다운로드이고, 캐시가 클수록 받는 데 오래 걸려요.
- **덜 저장하기.** `node_modules`나 빌드 결과가 아니라 `~/.npm`이나 pnpm 스토어를 캐시하세요. 기본 브랜치에서만 저장하고, 모든 작업에서는 `actions/cache/restore`를, 한 작업에서만 `actions/cache/save`를 쓰세요. 내 시간이 들고, 캐시가 작으면 복원하는 것도 적어요.
- **키를 고치기.** 잠금 파일을 키로 쓰고, `restore-keys`를 더하고, 기본 브랜치에 대한 푸시에서 워크플로를 돌려 새 브랜치가 읽을 것이 있게 하세요.
- **디스크를 유지하는 자체 호스팅 실행기.** 다운로드도, 10 GB도 없어요. 대신 머신을 직접 운영해요. OS 업데이트, 캐시를 지우지 않으면서 작업 사이를 정리하기, 고장 나면 고치기.

## 답이 디스크를 유지하는 머신일 때

캐시는 머신이 잊어버리기 때문에 있어요. GitHub 호스팅 실행기는 작업마다 새 VM이라서, 작업이 상태를 GitHub 저장소에 저장했다가 다음번에 다시 가져와요. 남아 있는 머신에서는 그 상태가 이미 디스크에 있어요. 패키지 관리자 캐시, 도구 캐시, Docker 이미지와 빌드 캐시, 빌드 결과까지요.

차이는 실제 프로젝트의 CI에서 보여요. [그 프로젝트들의 작업을 직접 돌려 본 결과](https://skipbox.dev/ko/guides/rust-cache-slow-rust-ci)예요.

- **astro(Node.js, Turborepo):** GitHub에서 528초, turbo 캐시를 남기는 Skipbox 전용 머신에서 30초예요. 준비된 실행에서는 빌드 작업 40개를 돌리지 않고 재생해요.
- **helix(Rust):** 툴체인과 캐시 단계가 전용 머신에서 9~10초, GitHub에서 41~46초였어요.
- **tauri(Rust):** GitHub에서 246초, 작업 사이에 `target/`을 남기는 전용 머신에서 53초예요.

## Skipbox는 캐시를 내 머신에 남겨요

요금제마다 작업 사이에도 유지되는 내 계정 전용 머신이 따라와요.

- **패키지 캐시가 디스크에 남아요.** `~/.npm`, pnpm 스토어, 도구마다의 `~/.cache`, Go·Gradle·Cargo·Maven 캐시, 그리고 `setup-*`가 설치한 도구까지요. 복원할 것이 없어요.
- **Docker 이미지, 레이어, 빌드 캐시도 남아요.** `docker build`가 지난 빌드의 레이어를 다시 써요([Docker 레이어 캐시](https://skipbox.dev/ko/guides/docker-layer-cache-github-actions)).
- **actions/cache, setup-*, rust-cache는 바꿀 필요가 없어요.** 저장한 것이 GitHub 저장소가 아니라 머신 옆에, GitHub의 리포지토리당 10 GB보다 넓은 공간에 남고, 복원은 로컬에서 읽어요.
- **디스크에는 7일 만료가 없어요.** 작업 뒤 디스크가 거의 찰 때까지 아무것도 지우지 않고, 그때는 가장 오래전에 쓴 것부터 지워요.

S에서도 GitHub 캐시 공간의 7배 이상이에요. 작업은 레이블로 크기를 골라요.

| 레이블 | 머신 | 디스크 | 요금제 |
|---|---|---|---|
| `skipbox` | 4 vCPU · 16 GB | 80 GB | S, 월 $39 |
| `skipbox-8x16` | 8 vCPU · 16 GB | 160 GB | M, 월 $79 |
| `skipbox-16x32` | 16 vCPU · 32 GB | 320 GB | L, 월 $149 |

프라이빗 리포지토리의 `ubuntu-latest`는 CPU 2개, 8 GB, SSD 14 GB예요. Skipbox에서는 실행 시간이 무제한이에요. 4 vCPU로 월 20,000분이면 GitHub는 $222를 청구하고, Skipbox S는 $39로 $183 적어요.

## 옮기는 건 한 줄이에요

```yaml
jobs:
  test:
    runs-on: skipbox # was ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci && npm test
```

1. GitHub로 Skipbox에 로그인하세요.
2. Skipbox GitHub App을 설치하고 리포지토리를 고르세요.
3. `runs-on`을 바꾸고 푸시하세요.

캐시 단계는 그대로 두세요. 두 번째 실행이 첫 실행의 캐시를 머신에서 찾아요.

## 보안

- 머신은 내 계정만 써요. 다른 회사의 작업은 그 머신에서 돌지 않아요.
- 작업이 끝날 때마다 실행기의 자격 증명, 프로세스, 컨테이너를 지워요. ‘작업마다 새 VM’을 켜면 작업마다 새 머신에서 돌아요.
- 쓰기 권한이 없는 사람의 코드(포크에서 온 풀 리퀘스트 등)는 새 VM에서 돌고, 그 VM은 캐시를 읽을 수만 있고 바꿀 수는 없어요.

자세한 내용은 [작업을 분리하는 방식](https://docs.skipbox.dev/ko/isolation)에 있어요.

## 캐시가 빗나가는 작업으로 체험해 보세요

무료 체험은 7일 또는 작업 시간 3,000분 중 먼저 끝나는 쪽까지 무료이고, 카드가 필요 없어요. 그 작업을 `runs-on: skipbox`로 옮기고 두 번 돌린 뒤, 두 번째 실행의 복원과 설치 단계를 GitHub와 나란히 놓아 보세요.

## 자주 묻는 질문

### GitHub Actions 캐시 용량 한도는 얼마인가요?

기본은 리포지토리당 10 GB이고, 모든 브랜치와 워크플로가 함께 써요. 넘으면 GitHub는 새 항목을 저장한 뒤, 리포지토리가 한도 아래로 돌아올 때까지 마지막으로 읽은 시점이 오래된 항목부터 지워요. 7일 동안 어떤 작업도 읽지 않은 항목은 용량과 관계없이 지워요. Pro, Team, Enterprise 계정에서는 관리자가 한도와 일수를 늘릴 수 있어요. 10 GB를 넘는 저장 공간은 시간마다의 최대치로 재서 GB당 월 $0.07이 청구되고, 예산에 닿으면 다음 청구 주기까지 캐시가 읽기 전용이 돼요.

### GitHub Actions 캐시가 왜 이렇게 자주 밀려나나요?

리포지토리의 모든 것이 10 GB 하나를 나눠 쓰기 때문이에요. 브랜치, 풀 리퀘스트, 행렬 작업, OS마다 자기 항목을 저장하고, Docker의 type=gha 캐시도 같은 곳에 들어가요. 하루의 저장량이 한도를 넘으면 저장할 때마다 오래된 항목이 지워지고, 다음 작업은 필요했던 항목을 놓쳐요. GitHub는 이것을 캐시 스래싱이라고 불러요. 항목을 크기순으로 나열해 보면(gh cache list --sort size_in_bytes) 무엇이 채우고 있는지 보여요.

### 캐시 복원이 왜 처음부터 설치하는 것만큼 오래 걸리나요?

캐시가 맞아도 다운로드이기 때문이에요. GitHub 호스팅 실행기의 작업은 매번 새 VM에서 시작하므로, actions/cache가 매번 아카이브를 받아서 풀고, 캐시가 클수록 오래 걸려요. setup-node의 캐시가 되돌려 주는 건 node_modules가 아니라 패키지 관리자의 다운로드 캐시라서, 복원 뒤에도 npm ci가 모든 패키지를 설치해요. 디스크를 유지하는 실행기에서는 캐시가 이미 있고, 아무것도 받지 않아요.

### 새 브랜치에서 actions/cache가 왜 빗나가나요?

실행은 자기 브랜치와 기본 브랜치의 캐시를 복원할 수 있고, 풀 리퀘스트의 실행은 베이스 브랜치의 캐시도 복원할 수 있어요. 형제 브랜치의 캐시는 읽지 못해요. 그래서 기능 브랜치의 첫 실행은 기본 브랜치가 그 키를 저장해 두었을 때만 맞아요. 기본 브랜치에 대한 푸시에서 워크플로를 돌려 저장하게 하고, 부분 일치를 위해 restore-keys를 더하세요. cache-hit은 key와 정확히 일치할 때만 true예요.

### Skipbox는 Actions 캐시를 얼마나 남기나요?

GitHub의 리포지토리당 10 GB보다 많이, GitHub 저장소가 아니라 내 머신 옆에 남겨요. 클라우드 머신에서는 작업이 actions/cache, setup-*, rust-cache로 저장한 것이 머신 자체의 디스크에, 디스크의 절반까지 남아요(S는 80 GB, M은 160 GB, L은 320 GB 디스크). Skipbox 호스트에서는 호스트의 캐시가 리포지토리당 20 GB를 남겨요. 어느 쪽이든 항목은 마지막으로 쓴 뒤 7일 동안 남고, 브랜치 규칙은 GitHub와 같아요. 패키지 캐시와 Docker 레이어는 이 캐시를 거치지 않고, 디스크 자체에 남아요.

### Skipbox 머신의 캐시는 언제 지워지나요?

작업 사이에는 아무것도 지우지 않아요. 캐시는 머신에 남고, 작업 뒤 디스크가 거의 찼을 때만 가장 오래전에 쓴 것부터 지워요. 머신이 깨끗하게 다시 시작하는 건 초기화될 때로, ‘머신 초기화’를 누를 때, 이미지가 업데이트될 때(적어도 한 달에 한 번), 작업 뒤 상태 점검에 실패할 때, 작업이 6시간 한도에 닿을 때예요. 요금제가 끝나면 머신은 디스크와 함께 지워져요.

### 체험하는 데 비용이 얼마나 드나요?

들지 않아요. 무료 체험은 7일 또는 작업 시간 3,000분 중 먼저 끝나는 쪽까지이고, 카드가 필요 없어요. 캐시가 빗나가거나 복원이 느린 작업을 runs-on: skipbox 레이블로 옮기고 두 번 돌린 뒤, 두 번째 실행의 복원과 설치 단계를 GitHub와 비교해 보세요.

2026-11-16 업데이트 · https://skipbox.dev/ko/guides/github-actions-cache-size-limit
