upload-artifact / download-artifact

القطع الأثرية (Artifacts) upload-artifact / download-artifact

upload-artifact وdownload-artifact ينقلان ملفات بين jobs مختلفة داخل نفس الـ workflow، أو يحتفظان بها بعد انتهاء التشغيلة للتنزيل اليدوي.

بعكس actions/cache المصمم لتسريع تبعيات متكررة عبر تشغيلات مختلفة، الـ Artifacts مصممة لنقل ملفات من job لآخر داخل نفس التشغيلة — مثل تمرير ناتج البناء (dist/) من job البناء إلى job النشر، لأن كل job في GitHub Actions يعمل على جهاز افتراضي منفصل ولا يشارك ملفات job آخر تلقائياً. الـ job المستقبِل يجب أن يعلن الاعتماد على job المصدر عبر needs، وإلا فقد يحاول تنزيل artifact غير موجود بعد لأن jobs بلا needs تعمل بالتوازي.

retention-days يحدد كم يوماً يبقى الـ artifact متاحاً للتنزيل قبل حذفه تلقائياً (بحد أقصى يفرضه إعداد المستودع أو المؤسسة). يُستخدم هذا أيضاً للاحتفاظ بتقارير الاختبار أو صور فشل الاختبارات البصرية لمراجعتها لاحقاً حتى بعد انتهاء التشغيلة بالكامل.

الصياغة

- uses: actions/upload-artifact@v4
  with:
    name: <اسم القطعة>
    path: <مسار الملفات>

- uses: actions/download-artifact@v4
  with:
    name: <اسم القطعة>

📄 مثال

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

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist-files
          path: dist/

أهم النقاط

العنصر	الوظيفة
name	اسم القطعة، يُستخدم لاحقاً في download-artifact لتحديد أيّها تُنزَّل
path	الملفات أو المجلدات المراد رفعها؛ يدعم مسارات متعددة بفاصل \|
retention-days	عدد أيام بقاء القطعة قبل الحذف التلقائي
needs	ليس جزءاً من الـ artifact نفسه، لكنه إلزامي على الـ job المستقبِل ليضمن ترتيب التنفيذ

💡 نصائح عملية

استخدم artifacts لتمرير ناتج بناء ثقيل بين jobs بدل إعادة بنائه في كل job من الصفر
احتفظ بتقارير التغطية (coverage) ونتائج الاختبار كـ artifact حتى تراجعها بعد فشل التشغيلة دون إعادة تشغيلها

⚠️ أخطاء شائعة

نسيان needs على الـ job المستقبِل يجعله يحاول التنزيل قبل رفع القطعة فعلياً لأن jobs تعمل بالتوازي افتراضياً
تخزين أسرار أو بيانات حساسة داخل artifact — أي شخص بصلاحية قراءة على المستودع يمكنه تنزيلها

خصائص ذات صلة

actions/cache التخزين المؤقت للتبعيات

🎓 تريد فهم الصورة الكاملة خطوة بخطوة؟ ابدأ من مسار DEVOPS الكامل بالعربي.

📚 للتعمق التقني الكامل بالإنجليزية: MDN Web Docs