# کش لایه‌های Docker در GitHub Actions: چرا هر بیلد سرد شروع می‌شود و چطور لایه‌ها را نگه داریم

> هر جاب GitHub Actions روی یک ماشین مجازی تازه بدون build cache و بدون ایمیج pullشده‌ای از Docker شروع می‌شود، و builder پیش‌فرض setup-buildx-action خالی شروع می‌کند. cache-to و cache-from در buildx‏ (gha‏، registry‏، local) لایه‌ها را به‌صورت دانلود برمی‌گردانند، داخل ۱۰ GB‏ GitHub. رانری که build cache‏ Docker را روی دیسکش نگه می‌دارد به هیچ‌کدام نیاز ندارد، با قیمت ثابت ماهانه $۳۹.

کش لایه‌های Docker در هر اجرای GitHub Actions از بین می‌رود، چون هر جاب روی رانر میزبانی‌شده GitHub روی یک ماشین مجازی تازه شروع می‌شود: نه build cache، نه ایمیج pullشده. builder پیش‌فرض docker/setup-buildx-action‏ (`docker-container`) هم در هر جاب خالی شروع می‌شود و در پایان آن حذف می‌شود. راه حل معمول صادر کردن کش با buildx است. `cache-to: type=gha,mode=max` و `cache-from: type=gha` لایه‌ها را در کش Actions‏ GitHub نگه می‌دارند، ۱۰ GB برای هر مخزن و مشترک با همه کش‌های دیگر؛ `type=registry` آن‌ها را در registry شما نگه می‌دارد؛ `type=local` در پوشه‌ای که با actions/cache ذخیره می‌کنید. هر کدام یک بیلد دوباره را به یک آپلود و یک دانلود در هر اجرا تبدیل می‌کند.

Skipbox لایه‌ها را همان‌جا نگه می‌دارد که بیلد اجرا می‌شود. جاب‌های شما روی ماشین اختصاصی حسابتان اجرا می‌شوند، که ایمیج‌ها، لایه‌ها و build cache‏ Docker را بین جاب‌ها نگه می‌دارد، روی دیسکی ۸۰ GB در S در برابر 14 GB روی رانر GitHub. `docker build` و `docker compose build` از لایه‌های بیلد قبلی استفاده می‌کنند و ایمیج‌هایی که compose‏ pull کرده از قبل روی دیسک هستند. setup-buildx-action همان‌طور که هست کار می‌کند و builder آن هم این لایه‌ها را پیدا می‌کند. یک خط را به `runs-on: skipbox` تغییر دهید، با قیمت ثابت ماهانه $۳۹ و دقیقه‌های نامحدود.

- GitHub: برای هر جاب یک ماشین مجازی تازه، پس در هر اجرا نه لایه‌ای، نه ایمیجی، و یک builder خالی buildx
- Skipbox: build cache و ایمیج‌های Docker روی دیسک ماشین شما می‌مانند، پس لایه‌های بدون تغییر نه دوباره بیلد می‌شوند و نه دانلود
- 20,000 دقیقه در ماه روی 4 vCPU یعنی $۲۲۲ روی GitHub و $۳۹ روی Skipbox

**GitHub Actions با قیمت ثابت و دقیقه‌های نامحدود** Skipbox جاب‌های GitHub Actions شما را روی ماشین اختصاصی خودتان اجرا می‌کند: ماهانه $۳۹، هر چند دقیقه که اجرا کنید. لایه‌های Docker و کش وابستگی‌ها بین جاب‌ها می‌مانند، پس جاب بعدی فوراً شروع می‌شود.

رانری با چهار vCPU، ماهانه بیست هزار دقیقه: GitHub $۲۲۲ → Skipbox $۳۹. هر ماه $۱۸۳ صرفه‌جویی می‌کنید.

انتقال فقط یک خط است: `runs-on: skipbox`.

[شروع دوره آزمایشی رایگان ۷ روزه](https://app.skipbox.dev/sign-in?ref=g-docker-layer-cache-github-actions-fa)

## چرا هر بیلد سرد شروع می‌شود

- **برای هر جاب یک ماشین مجازی تازه.** [مرجع رانرهای GitHub](https://docs.github.com/en/actions/reference/runners/github-hosted-runners) می‌گوید هر رانر میزبانی‌شده GitHub یک ماشین مجازی (VM) تازه است که GitHub میزبانی‌اش می‌کند. هیچ چیزی که جاب قبلی بیلد یا pull کرده روی آن نیست.
- **یک builder خالی.** [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action) به‌طور پیش‌فرض یک builder با driver‏ `docker-container` می‌سازد و راه می‌اندازد، و `cleanup` آن (که به‌طور پیش‌فرض روشن است) builder را در پایان جاب حذف می‌کند.
- **14 GB دیسک.** `ubuntu-latest` یک مخزن خصوصی 2 CPU‏، 8 GB و 14 GB حافظه SSD دارد. یک ایمیج بزرگ، build cache آن و یک آرشیو کش برای باز کردن می‌توانند جا را تمام کنند ("no space left on device").

## backendهای کش buildx و هزینه هر کدام

از [cache backends](https://docs.docker.com/build/cache/backends/) و [مدیریت کش با GitHub Actions](https://docs.docker.com/build/ci/github-actions/cache/) در مستندات Docker:

| backend | لایه‌ها کجا می‌روند | هر اجرا چه می‌پردازد | محدودیت‌ها |
|---|---|---|---|
| `type=gha` | کش Actions‏ GitHub | لایه‌های تازه را آپلود می‌کند، لایه‌های لازم را دانلود می‌کند | ۱۰ GB برای هر مخزن همراه همه کش‌های دیگر، اول قدیمی‌ترها حذف می‌شوند؛ scope پیش‌فرض `buildkit` با هر بیلد بازنویسی می‌شود؛ API کش GitHub درخواست‌ها را محدود می‌کند |
| `type=registry` | یک ایمیج کش جدا در registry شما | کش را از registry‏ pull می‌کند و کش تازه را push می‌کند | ورود به registry با دسترسی push؛ فضا و ترافیک registry |
| `type=inline` | داخل خود ایمیج | ایمیج را pull می‌کند تا کشش را بخواند | فقط `mode=min`: لایه‌های stageهای میانی نگه داشته نمی‌شوند |
| `type=local` + actions/cache | پوشه‌ای که با actions/cache ذخیره می‌شود | کل پوشه را دانلود و باز می‌کند، بعد آپلودش می‌کند | با هر اجرا بزرگ‌تر می‌شود، مگر [`reset=true`](https://docs.docker.com/build/cache/backends/local/) (در Buildx 0.35.0 و بعد)؛ از ۱۰ GB کم می‌کند |

هر backendی که انتخاب کنید، [Dockerfile را مرتب کنید](https://docs.docker.com/build/cache/optimize/) تا لایه‌هایی که کمتر تغییر می‌کنند اول بیایند: فایل lock را کپی کنید و وابستگی‌ها را پیش از کپی کردن سورس نصب کنید. وگرنه هر کامیت لایه نصب را باطل می‌کند و هیچ کشی آن را برنمی‌گرداند.

`mode=min`، که پیش‌فرض است، فقط لایه‌های ایمیج نهایی را نگه می‌دارد. `mode=max` لایه‌های همه stageها را نگه می‌دارد، پس یک بیلد چندمرحله‌ای کش بیشتری پیدا می‌کند، و بیشتر آپلود می‌کند.

یک چیدمان معمول `type=gha`، با scope جدا برای هر ایمیج:

```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
```

**cache mountها نمی‌مانند.** `RUN --mount=type=cache` (کش یک package manager داخل بیلد) به‌طور پیش‌فرض در کش GitHub Actions نگه داشته نمی‌شود؛ مستندات Docker به [buildkit-cache-dance](https://github.com/reproducible-containers/buildkit-cache-dance) اشاره می‌کند تا آن را به actions/cache ببرد و برگرداند، یعنی یک دانلود و آپلود دیگر در هر اجرا.

## docker compose در هر جاب همه ایمیج‌ها را pull می‌کند

تست‌های یکپارچگی که Postgres‏، Redis و چند سرویس را با `docker compose up` راه می‌اندازند، در هر جاب همه ایمیج‌ها را pull می‌کنند، چون ماشین مجازی تازه است. روی رانرهای میزبانی‌شده GitHub گزینه‌ها فقط دانلود را جابه‌جا می‌کنند:

- ایمیج‌ها را با `docker save` در یک فایل tar بنویسید، با actions/cache کشش کنید و در جاب بعدی `docker load` کنید. این از ۱۰ GB کم می‌کند و load خودش هم زمان می‌برد.
- ایمیج‌های سرویس‌ها را با buildx و یکی از backendهای بالا بیلد کنید، که باز هم ایمیج‌های پایه را برای pull باقی می‌گذارد.

## وقتی راه حل ماشینی است که کش Docker را نگه می‌دارد

همه backendهای بالا به این دلیل وجود دارند که builder فراموش می‌کند. یک Docker daemon که بین جاب‌ها می‌ماند، لایه‌های بیلد قبلی، cache mountهایش و همه ایمیج‌هایی را که pull کرده از قبل روی دیسک خودش دارد. چیزی برای صادر کردن، چیزی برای وارد کردن و هیچ ۱۰ GB مشترکی وجود ندارد.

## Skipbox کش Docker را روی ماشین شما نگه می‌دارد

هر طرح با ماشین اختصاصی حساب شما می‌آید که بین جاب‌ها می‌ماند:

- **`docker build` و `docker compose build`** از لایه‌های بیلد قبلی استفاده می‌کنند، بدون تغییر در ورک‌فلو.
- **ایمیج‌ها روی دیسک می‌مانند.** `docker compose up` ایمیج‌هایی را که دفعه قبل pull کرده پیدا می‌کند؛ `docker compose pull` فقط لایه‌هایی را می‌گیرد که تغییر کرده‌اند.
- **cache mountها می‌مانند**، همراه build cache‏ Docker، پس `RUN --mount=type=cache` کش package manager را بدون هیچ گام اضافه‌ای نگه می‌دارد.
- **docker/setup-buildx-action همان‌طور که هست کار می‌کند.** builder آن از لایه‌هایی شروع می‌کند که بیلد قبلی مخزن شما روی ماشین گذاشته است، و می‌توانید `cache-from` و `cache-to` را حذف کنید. در اجرای خود ما از CI یک پروژهٔ عمومی روی ماشینی با 4 vCPU (19 نوامبر 2026، هر کدام یک اجرا)، گام بیلد ایمیج در اجرای اول 177 ثانیه و در اجرای دوباره 4 ثانیه طول کشید و 31 گام CACHED بود.
- **دیسک:** تا وقتی دیسک بعد از یک جاب تقریباً پر نشود هیچ چیز حذف نمی‌شود. آن وقت اول ایمیج‌های بی‌برچسب (dangling) می‌روند، بعد build cacheی که از همه قدیمی‌تر استفاده شده.

```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` | ۴ vCPU · ۱۶ GB | ۸۰ GB | S، ماهانه $۳۹ |
| `skipbox-8x16` | ۸ vCPU · ۱۶ GB | ۱۶۰ GB | M، ماهانه $۷۹ |
| `skipbox-16x32` | ۱۶ vCPU · ۳۲ GB | ۳۲۰ GB | L، ماهانه $۱۴۹ |

دقیقه‌ها نامحدودند. با 20,000 دقیقه در ماه روی 4 vCPU‏، GitHub‏ $۲۲۲ می‌گیرد؛ Skipbox S‏ $۳۹ است، یعنی $۱۸۳ کمتر.

## انتقال یک خط است

1. با GitHub وارد Skipbox شوید.
2. اپ Skipbox در GitHub را نصب کنید و مخزن‌ها را انتخاب کنید.
3. `runs-on` را تغییر دهید و push کنید.

جاب اول همه لایه‌ها را بیلد می‌کند. جاب دوم آن‌ها را روی ماشین پیدا می‌کند.

## امنیت

- ماشین فقط مال حساب شماست. جاب هیچ شرکت دیگری روی آن اجرا نمی‌شود.
- بعد از هر جاب، اعتبارنامه‌های رانر، پروسه‌ها و کانتینرها پاک می‌شوند، و همین‌طور `~/.docker/config.json`، پس ورود به یک registry به جاب بعدی منتقل نمی‌شود. گزینه «ماشین تازه برای هر جاب» به‌جای آن به هر جاب یک ماشین تازه می‌دهد.
- کد افرادی که دسترسی نوشتن ندارند (مثل pull requestها از forkها) روی یک ماشین تازه و یک‌بارمصرف اجرا می‌شود، هرگز روی ماشین شما.

جزئیات در [جداسازی جاب‌ها](https://docs.skipbox.dev/fa/isolation) است.

## روی بیلد Docker خودتان امتحانش کنید

دوره آزمایشی به مدت ۷ روز یا ۳٬۰۰۰ دقیقه جاب رایگان است، هر کدام زودتر برسد، و کارت نمی‌خواهد. بیلد Docker خود را به `runs-on: skipbox` ببرید، دو بار اجرایش کنید و گام بیلد اجرای دوم را کنار GitHub بگذارید.

## پرسش‌های متداول

### چرا کش لایه‌های Docker در هر اجرای GitHub Actions از بین می‌رود؟

چون هر جاب روی رانر میزبانی‌شده GitHub روی یک ماشین مجازی تازه شروع می‌شود، بدون build cache و بدون ایمیجی از اجرای قبلی. docker/setup-buildx-action هم به آن اضافه می‌کند: به‌طور پیش‌فرض یک builder از نوع docker-container می‌سازد که خالی شروع می‌شود و در پایان جاب حذف می‌شود. پس هر لایه دوباره بیلد می‌شود، مگر کش را با cache-to صادر و با cache-from وارد کنید، یا روی ماشینی اجرا کنید که build cache‏ Docker را نگه می‌دارد.

### چطور لایه‌های Docker را در GitHub Actions کش کنم؟

روی رانرهای میزبانی‌شده GitHub، با cache exporterهای buildx:‏ cache-from: type=gha و cache-to: type=gha,mode=max در docker/build-push-action لایه‌ها را در کش Actions‏ GitHub ذخیره می‌کنند (۱۰ GB برای هر مخزن، مشترک با همه کش‌های دیگر). type=registry آن‌ها را به‌صورت یک ایمیج جدا در registry شما ذخیره می‌کند، و type=local در پوشه‌ای که با actions/cache ذخیره می‌کنید. با type=gha به هر ایمیج scope خودش را بدهید، چون scope پیش‌فرض با هر بیلد بازنویسی می‌شود. روی ماشینی که دیسکش را نگه می‌دارد، docker build بدون هیچ exporterی از لایه‌ها دوباره استفاده می‌کند.

### چرا buildx با cache-to type=gha هنوز کند است؟

چون لایه‌ها هنوز جابه‌جا می‌شوند. با mode=max، هر اجرا همه لایه‌های تازه همه stageها را آپلود می‌کند و اجرای بعدی لایه‌هایی را که لازم دارد دانلود می‌کند. این کش ۱۰ GB هر مخزن در GitHub را با همه چیزهای دیگر شریک است، پس حذف می‌شود، و API کش GitHub بیلدی را که درخواست‌های زیادی بفرستد محدود می‌کند. builderی که لایه‌ها را از قبل روی دیسکش دارد از هر دو جهت می‌گذرد.

### چطور جلوی pull همان ایمیج‌ها در هر جاب توسط docker compose را بگیرم؟

روی رانر میزبانی‌شده GitHub نمی‌توانید، فقط می‌توانید دانلود را جابه‌جا کنید: ایمیج‌ها را با docker save در یک فایل tar بنویسید، با actions/cache کشش کنید و در جاب بعدی docker load کنید. این از همان ۱۰ GB کم می‌کند و در هر اجرا یک دانلود و یک load است. روی ماشینی که دیسکش را نگه می‌دارد، ایمیج‌هایی که compose دفعه قبل pull کرده از قبل آنجا هستند و docker compose pull فقط لایه‌هایی را می‌گیرد که تغییر کرده‌اند.

### برای نگه داشتن کش Docker روی Skipbox باید ورک‌فلوی خود را تغییر دهم؟

فقط runs-on: ماشین اختصاصی شما ایمیج‌ها، لایه‌ها و build cache‏ Docker را بین جاب‌ها نگه می‌دارد. docker build و docker compose build دوباره از آن‌ها استفاده می‌کنند، و docker/setup-buildx-action همان‌طور که هست کار می‌کند: builder آن از لایه‌هایی شروع می‌کند که بیلد قبلی مخزن شما روی ماشین گذاشته است. می‌توانید cache-from و cache-to را حذف کنید.

### امتحان کردنش چقدر هزینه دارد؟

هیچ. دوره آزمایشی ۷ روز یا ۳٬۰۰۰ دقیقه جاب است، هر کدام زودتر برسد، و کارت نمی‌خواهد. بیلد Docker خود را به runs-on: skipbox ببرید، دو بار اجرایش کنید و گام بیلد اجرای دوم را با GitHub مقایسه کنید.

به‌روزرسانی: 2026-11-19 · https://skipbox.dev/fa/guides/docker-layer-cache-github-actions
