کش لایههای Docker در GitHub Actions: چرا هر بیلد سرد شروع میشود و چطور لایهها را نگه داریم
کش لایههای 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 میگوید هر رانر میزبانیشده GitHub یک ماشین مجازی (VM) تازه است که GitHub میزبانیاش میکند. هیچ چیزی که جاب قبلی بیلد یا pull کرده روی آن نیست.
- یک builder خالی. 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 و مدیریت کش با GitHub Actions در مستندات 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 (در Buildx 0.35.0 و بعد)؛ از ۱۰ GB کم میکند |
هر backendی که انتخاب کنید، Dockerfile را مرتب کنید تا لایههایی که کمتر تغییر میکنند اول بیایند: فایل lock را کپی کنید و وابستگیها را پیش از کپی کردن سورس نصب کنید. وگرنه هر کامیت لایه نصب را باطل میکند و هیچ کشی آن را برنمیگرداند.
mode=min، که پیشفرض است، فقط لایههای ایمیج نهایی را نگه میدارد. mode=max لایههای همه stageها را نگه میدارد، پس یک بیلد چندمرحلهای کش بیشتری پیدا میکند، و بیشتر آپلود میکند.
یک چیدمان معمول type=gha، با scope جدا برای هر ایمیج:
- 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 اشاره میکند تا آن را به 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ی که از همه قدیمیتر استفاده شده.
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 $۳۹ است، یعنی $۱۸۳ کمتر.
انتقال یک خط است
- با GitHub وارد Skipbox شوید.
- اپ Skipbox در GitHub را نصب کنید و مخزنها را انتخاب کنید.
runs-onرا تغییر دهید و push کنید.
جاب اول همه لایهها را بیلد میکند. جاب دوم آنها را روی ماشین پیدا میکند.
امنیت
- ماشین فقط مال حساب شماست. جاب هیچ شرکت دیگری روی آن اجرا نمیشود.
- بعد از هر جاب، اعتبارنامههای رانر، پروسهها و کانتینرها پاک میشوند، و همینطور
~/.docker/config.json، پس ورود به یک registry به جاب بعدی منتقل نمیشود. گزینه «ماشین تازه برای هر جاب» بهجای آن به هر جاب یک ماشین تازه میدهد. - کد افرادی که دسترسی نوشتن ندارند (مثل pull requestها از forkها) روی یک ماشین تازه و یکبارمصرف اجرا میشود، هرگز روی ماشین شما.
جزئیات در جداسازی جابها است.
روی بیلد 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 مقایسه کنید.
بهروزرسانی: ۲۸ آبان ۱۴۰۵