# GitHub Actions의 Docker 레이어 캐시: 빌드가 매번 처음부터인 이유와 레이어를 남기는 방법

> GitHub Actions의 작업은 Docker 빌드 캐시도, 받아 둔 이미지도 없는 새 VM에서 시작하고, setup-buildx-action의 기본 빌더도 비어 있는 채로 시작해요. buildx의 cache-to와 cache-from(gha, registry, local)은 GitHub의 10 GB 안에서 레이어를 다운로드로 되돌려 줄 뿐이에요. Docker 빌드 캐시를 디스크에 남기는 실행기라면 아무것도 필요 없고, 월 $39 정액이에요.

GitHub Actions 실행마다 Docker 레이어 캐시가 사라지는 건, GitHub 호스팅 실행기의 작업이 빌드 캐시도, 받아 둔 이미지도 없는 새 VM에서 시작하기 때문이에요. docker/setup-buildx-action의 기본 빌더(`docker-container`)도 작업마다 비어 있는 채로 시작하고, 작업 끝에 지워져요. 흔한 해결책은 buildx로 캐시를 내보내는 거예요. `cache-to: type=gha,mode=max`와 `cache-from: type=gha`는 레이어를 GitHub의 Actions 캐시에 두고, 이 캐시는 리포지토리당 10 GB이며 다른 모든 캐시와 공유돼요. `type=registry`는 레지스트리에, `type=local`은 actions/cache로 저장하는 디렉터리에 둬요. 어느 쪽이든 다시 빌드를 실행마다의 업로드와 다운로드로 바꿀 뿐이에요.

Skipbox는 빌드가 도는 곳에 레이어를 남겨요. 작업은 내 계정 전용 머신에서 돌고, 그 머신이 작업 사이에도 Docker 이미지, 레이어, 빌드 캐시를 남겨요. 디스크는 S가 80 GB이고, GitHub 실행기는 14 GB예요. `docker build`와 `docker compose build`는 지난 빌드의 레이어를 다시 쓰고, compose가 받은 이미지는 이미 디스크에 있어요. setup-buildx-action은 그대로 두면 되고, 그 빌더도 이 레이어를 찾아요. `runs-on: skipbox` 한 줄만 바꾸면 월 $39 정액에 실행 시간 무제한이에요.

- GitHub: 작업마다 새 VM이라서, 레이어도 이미지도 없고 buildx 빌더도 매번 비어 있어요
- Skipbox: Docker 빌드 캐시와 이미지가 내 머신의 디스크에 남아서, 바뀌지 않은 레이어는 다시 빌드하지도 받지도 않아요
- 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-docker-layer-cache-github-actions-ko)

## 빌드가 매번 처음부터인 이유

- **작업마다 새 VM.** GitHub의 [실행기 문서](https://docs.github.com/en/actions/reference/runners/github-hosted-runners)에 따르면, GitHub 호스팅 실행기는 매번 GitHub가 호스팅하는 새 가상 머신(VM)이에요. 지난 작업이 빌드하거나 받은 것은 하나도 없어요.
- **비어 있는 빌더.** [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action)은 기본적으로 `docker-container` 드라이버로 빌더를 만들어 띄우고, 기본으로 켜져 있는 `cleanup`이 작업 끝에 그 빌더를 지워요.
- **14 GB 디스크.** 프라이빗 리포지토리의 `ubuntu-latest`는 CPU 2개, 8 GB, SSD 14 GB예요. 큰 이미지와 그 빌드 캐시, 풀어야 할 캐시 아카이브가 겹치면 공간이 모자랄 수 있어요("no space left on device").

## buildx 캐시 백엔드와 각각의 비용

Docker의 [캐시 백엔드](https://docs.docker.com/build/cache/backends/)와 [GitHub Actions의 캐시 관리](https://docs.docker.com/build/ci/github-actions/cache/) 문서에 따르면:

| 백엔드 | 레이어가 가는 곳 | 실행마다 치르는 것 | 한계 |
|---|---|---|---|
| `type=gha` | GitHub의 Actions 캐시 | 새 레이어를 올리고, 필요한 레이어를 받아요 | 다른 모든 캐시와 함께 리포지토리당 10 GB, 오래된 것부터 밀려나요. 기본 scope `buildkit`은 빌드마다 덮어써지고, GitHub의 캐시 API가 속도를 제한해요 |
| `type=registry` | 레지스트리의 별도 캐시 이미지 | 레지스트리에서 캐시를 받고, 새 캐시를 올려요 | 푸시 권한이 있는 레지스트리 로그인, 레지스트리의 저장 공간과 트래픽 |
| `type=inline` | 이미지 안 | 캐시를 읽으려고 이미지를 받아요 | `mode=min`만 돼요. 중간 스테이지의 레이어는 남지 않아요 |
| `type=local` + actions/cache | actions/cache로 저장하는 디렉터리 | 디렉터리 전체를 받아서 풀고, 다시 올려요 | [`reset=true`](https://docs.docker.com/build/cache/backends/local/)(Buildx 0.35.0 이상)가 아니면 실행마다 커져요. 10 GB에 들어가요 |

어떤 백엔드를 고르든, 가장 덜 바뀌는 레이어가 앞에 오도록 [Dockerfile의 순서를 정하세요](https://docs.docker.com/build/cache/optimize/). 소스를 복사하기 전에 잠금 파일을 복사하고 의존성을 설치하세요. 그러지 않으면 커밋마다 설치 레이어가 무효가 되고, 어떤 캐시로도 되돌릴 수 없어요.

기본값인 `mode=min`은 최종 이미지의 레이어만 남겨요. `mode=max`는 모든 스테이지의 레이어를 남기므로, 멀티 스테이지 빌드에서 캐시가 더 잘 맞는 대신 더 많이 올려요.

이미지마다 scope를 따로 준 흔한 `type=gha` 설정이에요.

```yaml
- uses: docker/setup-buildx-action@v4
- uses: docker/build-push-action@v7
  with:
    context: .
    tags: app:ci
    load: true
    cache-from: type=gha,scope=app
    cache-to: type=gha,scope=app,mode=max
```

**캐시 마운트는 남지 않아요.** `RUN --mount=type=cache`(빌드 안의 패키지 관리자 캐시)는 기본적으로 GitHub Actions 캐시에 남지 않아요. Docker 문서는 이것을 actions/cache로 넣고 빼는 [buildkit-cache-dance](https://github.com/reproducible-containers/buildkit-cache-dance)를 안내하는데, 실행마다 다운로드와 업로드가 하나씩 더 생겨요.

## docker compose는 작업마다 모든 이미지를 받아요

`docker compose up`으로 Postgres, Redis, 서비스 몇 개를 띄우는 통합 테스트는 VM이 새것이라서 작업마다 모든 이미지를 받아요. GitHub 호스팅 실행기에서 할 수 있는 건 다운로드 위치를 옮기는 것뿐이에요.

- `docker save`로 이미지를 tar 파일로 저장하고, actions/cache로 캐시하고, 다음 작업에서 `docker load`로 불러와요. 10 GB에 들어가고, 불러오는 데도 시간이 따로 들어요.
- 서비스 이미지를 buildx와 위의 캐시 백엔드로 빌드해요. 그래도 베이스 이미지는 받아야 해요.

## 답이 Docker 캐시를 남기는 머신일 때

위의 백엔드는 모두 빌더가 잊어버리기 때문에 있는 거예요. 작업 사이에도 남아 있는 Docker 데몬은 지난 빌드의 레이어, 캐시 마운트, 받아 둔 모든 이미지를 이미 자기 디스크에 갖고 있어요. 내보낼 것도, 가져올 것도, 나눠 쓸 10 GB도 없어요.

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

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

- **`docker build`와 `docker compose build`**는 워크플로를 바꾸지 않아도 지난 빌드의 레이어를 다시 써요.
- **이미지가 디스크에 남아요.** `docker compose up`은 지난번에 받은 이미지를 찾고, `docker compose pull`은 바뀐 레이어만 받아요.
- **캐시 마운트도 남아요.** Docker 빌드 캐시와 함께 남으므로, `RUN --mount=type=cache`가 추가 단계 없이 패키지 관리자 캐시를 유지해요.
- **docker/setup-buildx-action은 그대로 두면 돼요.** 그 빌더는 내 리포지토리의 지난 빌드가 머신에 남긴 레이어에서 시작하고, `cache-from`과 `cache-to`는 지워도 돼요. 공개 프로젝트의 CI를 4 vCPU 머신에서 직접 돌려 보니(2026년 11월 19일, 각 1회), 이미지 빌드 단계가 첫 실행에서 177초, 다시 실행했을 때 4초 걸렸고 31개 단계가 CACHED였어요.
- **디스크:** 작업이 끝난 뒤 디스크가 거의 찰 때까지는 아무것도 지우지 않아요. 그때가 되면 dangling 이미지부터, 그다음 가장 오래전에 쓴 빌드 캐시를 지워요.

```yaml
jobs:
  build:
    runs-on: skipbox # was ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v4
      - uses: docker/build-push-action@v7
        with:
          context: .
          tags: app:ci
          load: true
```

작업은 레이블로 크기를 골라요.

| 레이블 | 머신 | 디스크 | 요금제 |
|---|---|---|---|
| `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 |

실행 시간은 무제한이에요. 4 vCPU로 월 20,000분이면 GitHub는 $222를 청구하고, Skipbox S는 $39로 $183 적어요.

## 옮기는 건 한 줄이에요

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

첫 작업은 모든 레이어를 빌드해요. 두 번째 작업은 머신에서 찾아요.

## 보안

- 머신은 내 계정만 써요. 다른 회사의 작업은 그 머신에서 돌지 않아요.
- 작업이 끝날 때마다 실행기의 자격 증명, 프로세스, 컨테이너를 지우고, `~/.docker/config.json`도 지워서 레지스트리 로그인이 다음 작업으로 넘어가지 않아요. ‘작업마다 새 VM’을 켜면 작업마다 새 머신에서 돌아요.
- 쓰기 권한이 없는 사람의 코드(포크에서 온 풀 리퀘스트 등)는 내 머신이 아니라 한 번 쓰고 버리는 새 머신에서 돌아요.

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

## Docker 빌드로 체험해 보세요

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

## 자주 묻는 질문

### GitHub Actions 실행마다 Docker 레이어 캐시가 왜 사라지나요?

GitHub 호스팅 실행기의 작업은 빌드 캐시도, 지난 실행의 이미지도 없는 새 VM에서 시작하기 때문이에요. docker/setup-buildx-action이 여기에 더해요. 기본적으로 비어 있는 상태로 시작해 작업 끝에 지워지는 docker-container 빌더를 만들어요. 그래서 cache-to로 캐시를 내보내고 cache-from으로 가져오거나, Docker 빌드 캐시를 남기는 머신에서 돌리지 않으면 모든 레이어를 다시 빌드해요.

### GitHub Actions에서 Docker 레이어를 캐시하려면 어떻게 하나요?

GitHub 호스팅 실행기에서는 buildx의 캐시 내보내기를 써요. docker/build-push-action에 cache-from: type=gha와 cache-to: type=gha,mode=max를 쓰면 레이어가 GitHub의 Actions 캐시(리포지토리당 10 GB, 다른 모든 캐시와 공유)에 저장돼요. type=registry는 레지스트리에 별도 이미지로, type=local은 actions/cache로 저장하는 디렉터리에 저장해요. type=gha에서는 이미지마다 scope를 따로 주세요. 기본 scope는 빌드마다 덮어써지기 때문이에요. 디스크를 유지하는 머신에서는 내보내기 없이 docker build가 레이어를 다시 써요.

### buildx에 cache-to type=gha를 넣었는데 왜 여전히 느린가요?

레이어가 여전히 오가기 때문이에요. mode=max면 실행마다 모든 스테이지의 새 레이어를 올리고, 다음 실행이 필요한 레이어를 받아요. 캐시는 GitHub의 리포지토리당 10 GB를 다른 모든 것과 나눠 쓰므로 밀려나고, 요청이 너무 많은 빌드는 GitHub의 캐시 API가 속도를 제한해요. 레이어를 이미 디스크에 가진 빌더는 양방향을 다 건너뛰어요.

### docker compose가 작업마다 같은 이미지를 받지 않게 하려면 어떻게 하나요?

GitHub 호스팅 실행기에서는 막을 수 없고, 다운로드 위치만 옮길 수 있어요. docker save로 이미지를 tar 파일로 저장하고, actions/cache로 캐시하고, 다음 작업에서 docker load로 불러와요. 같은 10 GB에 들어가고, 실행마다 받고 불러와야 해요. 디스크를 유지하는 머신에서는 compose가 지난번에 받은 이미지가 이미 있고, docker compose pull은 바뀐 레이어만 받아요.

### Skipbox에서 Docker 캐시를 남기려면 워크플로를 바꿔야 하나요?

runs-on만 바꾸면 돼요. 내 전용 머신이 작업 사이에도 Docker 이미지, 레이어, 빌드 캐시를 남겨요. docker build와 docker compose build가 그것을 다시 쓰고, docker/setup-buildx-action도 그대로 두면 돼요. 그 빌더는 내 리포지토리의 지난 빌드가 머신에 남긴 레이어에서 시작해요. cache-from과 cache-to는 지워도 돼요.

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

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

2026-11-19 업데이트 · https://skipbox.dev/ko/guides/docker-layer-cache-github-actions
