Skipbox

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

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 정액에 실행 시간 무제한이에요.

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

  • 작업마다 새 VM. GitHub의 실행기 문서에 따르면, GitHub 호스팅 실행기는 매번 GitHub가 호스팅하는 새 가상 머신(VM)이에요. 지난 작업이 빌드하거나 받은 것은 하나도 없어요.
  • 비어 있는 빌더. 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의 캐시 백엔드와 GitHub Actions의 캐시 관리 문서에 따르면:

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

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

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

- 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를 안내하는데, 실행마다 다운로드와 업로드가 하나씩 더 생겨요.

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 이미지부터, 그다음 가장 오래전에 쓴 빌드 캐시를 지워요.
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

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

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

옮기는 건 한 줄이에요

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

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

보안

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

자세한 내용은 작업을 분리하는 방식에 있어요.

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일 업데이트

캐시가 늘 살아 있는 더 빠른 CI/CD

캐시가 남는 전용 실행기를 정액으로

머신은 Skipbox가 준비해요. 바꿀 건 한 줄뿐이에요. 최대로 쓰면 비용은 GitHub의 1/12. 정액이라 하루 종일 돌려도 돼요. 캐시 용량은 GitHub의 7배.

  • 카드 불필요
  • GitHub로 로그인
  • 언제든 해지