runs.using: composite

Composite Action runs.using: composite

composite action تحزم عدة خطوات متكررة في action واحد يُستدعى كخطوة واحدة داخل أي job، لتفادي تكرار نفس الخطوات في workflows متعددة.

composite action مجرد ملف action.yml يحدد runs.using: composite بدل using: node20 أو using: docker، ويحتوي قائمة steps عادية تُنفَّذ بالترتيب عند استدعاء الـ action. كل خطوة داخلها تحتاج shell صراحة (عادة bash) لأنها لا ترث shell الـ job المستدعي تلقائياً. تُستدعى من نفس المستودع بـ uses: ./.github/actions/<اسم-المجلد>، أو من مستودع منفصل بـ uses: owner/repo@ref.

الفرق الجوهري عن workflow_call: composite action تعمل داخل job موجود مسبقاً ولا يمكنها تعريف jobs جديدة أو تغيير نوع الـ runner، بينما workflow_call يستدعي jobs كاملة بإعداداتها الخاصة. في سجل تشغيل الـ workflow، composite action تظهر كخطوة واحدة مجمّعة، لا كل خطوة داخلية على حدة.

الصياغة

# action.yml
runs:
  using: "composite"
  steps:
    - run: <أمر>
      shell: bash

📄 مثال

# .github/actions/setup-project/action.yml
name: "Setup Project"
inputs:
  node-version:
    default: "20"
runs:
  using: "composite"
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
    - run: npm ci
      shell: bash

# الاستدعاء من workflow:
# - uses: ./.github/actions/setup-project
#   with:
#     node-version: "22"

أهم النقاط

العنصر	الوظيفة
runs.using	يجب أن تكون قيمته "composite" ليتعرف GitHub على نوع الـ action
steps	قائمة خطوات تُنفَّذ بالترتيب، كل واحدة تحتاج shell صراحة
inputs	مدخلات يمررها الـ caller عبر with، تُقرأ داخل الخطوات بـ inputs.<name>
outputs	قيم يُرجعها الـ action مبنية من مُخرَجات خطوة داخلية عبر steps.<id>.outputs

💡 نصائح عملية

استخدمها لتجميع خطوات تحضيرية متكررة (تثبيت تبعيات، تسجيل دخول لسجل حاويات) تتكرر في أكثر من workflow
composite action من مستودع منفصل يجب أن يكون المستودع عاماً (public) ليُستدعى من مستودعات أخرى

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

نسيان shell على خطوة run داخل composite action يسبب فشل الترجمة فوراً — لا تُورَث shell الـ job المستدعي
محاولة تعريف job منفصل أو runner مختلف داخل composite action — غير مدعوم، composite تعمل ضمن job المستدعي فقط

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

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