التخزين المؤقت والقطع الأثرية في GitHub Actions

المشكلة: workflows بطيئة تكرر نفس العمل

كل مرة يشتغل فيها workflow، تُنزَّل التبعيات (node_modules، pip packages، Go modules...) من الصفر — دقائق ضائعة في كل تشغيل رغم أن ملف القفل (lock file) لم يتغيّر. GitHub Actions يحل هذا بأداتين مختلفتين تماماً في غرضهما: Cache لإعادة استخدام ملفات بين تشغيلات مختلفة، وArtifacts لتمرير ملفات بين jobs داخل نفس التشغيلة أو للاحتفاظ بها بعد انتهائها.

Cache: تسريع التثبيت المتكرر

actions/cache يخزّن مجلداً أو ملفات بمفتاح (key) محدد، ويحاول استرجاعها في التشغيلات القادمة بدل إعادة تحميلها.

- name: Cache node modules
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

• key: المفتاح المطلوب مطابقته تماماً لاسترجاع الكاش. بناؤه من hashFiles() على ملف القفل يضمن أن أي تغيير بالتبعيات يولّد مفتاحاً جديداً تلقائياً (cache miss مقصود)
• path: المسار المراد تخزينه — يدعم أنماط glob ومسارات متعددة
• restore-keys: مفاتيح احتياطية تُجرَّب بالترتيب إذا لم يوجد تطابق تام لـ key — تسترجع أقرب كاش سابق حتى لو لم يطابق بدقة (partial match)

عند عدم وجود مطابقة (cache miss)، ينشئ الـ job كاشاً جديداً تلقائياً بعد نجاحه — لا حاجة لخطوة "حفظ" منفصلة.

- name: Install dependencies
  run: npm ci

⚠️ لست مضطراً لكتابة actions/cache يدوياً دائماً: setup-node، setup-python، setup-java، setup-go وغيرها تدعم تخزيناً مؤقتاً مدمجاً بخيار واحد:

نسخ

- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: 'npm'

Artifacts: تمرير الملفات بين Jobs

الكاش مصمم للتبعيات المتكررة عبر تشغيلات مختلفة. Artifacts مختلفة: تُستخدم لنقل ملفات من job لآخر داخل نفس الـ workflow، مثل تمرير ناتج البناء (build output) من job البناء إلى job النشر، أو الاحتفاظ بتقارير الاختبار بعد انتهاء التشغيلة.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - name: Upload build output
        uses: actions/upload-artifact@v4
        with:
          name: dist-files
          path: dist/
          retention-days: 5

  deploy:
    needs: build   # ينتظر انتهاء build بنجاح
    runs-on: ubuntu-latest
    steps:
      - name: Download build output
        uses: actions/download-artifact@v4
        with:
          name: dist-files
          path: dist/
      - run: echo "انشر محتوى dist/ الآن"

• needs: build إلزامي — بدونه سيحاول job الـ deploy تنزيل artifact غير موجود بعد لأن الـ jobs تعمل بالتوازي افتراضياً
• retention-days يحدد مدة بقاء الملف على خوادم GitHub (بحد أقصى يفرضه إعداد المستودع/المؤسسة) — بعدها يُحذف تلقائياً
• يمكن رفع مسارات متعددة أو أنماط glob بفاصل | ضمن نفس artifact واحد

متى تستخدم أيهما؟

⚠️ لا تخزّن أسراراً أو بيانات حساسة داخل Artifacts — أي شخص لديه صلاحية قراءة على المستودع يمكنه تنزيلها ما دامت لم تنتهِ صلاحيتها.

تحديث 2026: مدة الاحتفاظ لم تعد تخص الـ Artifacts وحدها

حتى الآن، إعداد الاحتفاظ (retention) في هذا الدرس كان يخص الـ Artifacts والسجلّات (logs) فقط — أما تاريخ التشغيلات نفسه (workflow runs)، وحالات الفحوصات (checks)، وحالات الـ commit (statuses)، فكانت تبقى محفوظة على خوادم GitHub لأكثر من 400 يوم بغض النظر عن أي إعداد احتفاظ ضبطته، لأنها لم تكن خاضعة لنفس القاعدة أصلاً.

اعتباراً من 1 أكتوبر 2026، تُطبَّق GitHub نفس إعداد الاحتفاظ المستخدم للـ Artifacts والسجلّات على التشغيلات وحالات الفحوصات والـ statuses أيضاً — القيمة الافتراضية 90 يوماً، وهي نفسها الحد الأقصى المسموح للمستودعات العامة (public). بعد هذا التاريخ، أي تشغيلة أقدم من مدة الاحتفاظ المضبوطة تُحذف تلقائياً مع سجلّاتها، تماماً كما يحدث اليوم مع الـ Artifacts منتهية الصلاحية.

• الإعداد نفسه (على مستوى المستودع أو المؤسسة) الذي يتحكم بمدة بقاء الـ Artifacts والسجلّات هو المسؤول الآن عن مدة بقاء تاريخ التشغيلات كاملاً — لا إعداد منفصل جديد
• لو كان مشروعك يعتمد على الرجوع لتشغيلة قديمة (أكثر من 90 يوماً) للتدقيق أو التحقيق في مشكلة سابقة، راجع قيمة الاحتفاظ المضبوطة قبل 1 أكتوبر 2026
• التغيير لا يمس الـ badges أو حالة آخر تشغيلة ناجحة على الفرع الرئيسي — يخص فقط الاحتفاظ بالتاريخ الكامل للتشغيلات القديمة

⚠️ لو مشروعك يحتاج أرشيف طويل الأمد لتشغيلات CI (لأغراض امتثال مثلاً)، لا تعتمد على الاحتفاظ الافتراضي لـ GitHub — صدّر البيانات التي تحتاجها فعلياً (تقارير، نتائج اختبار) كـ artifact منفصل بمدة احتفاظ أطول، أو خزّنها خارجياً.

🎯 التالي: Workflows قابلة لإعادة الاستخدام وComposite Actions