GitHub Actions: Reusable Workflow مقابل Composite Action

تجمع سير العمل القابلة لإعادة الاستخدام (reusable workflow) واحدة أو أكثر من الوظائف (jobs) ويتم استدعاؤها على مستوى الوظيفة باستخدام uses:؛ بينما يجمع الإجراء المركب (composite action) خطوات (steps) ويعمل كخطوة واحدة داخل وظيفة. استخدم سير العمل القابلة لإعادة الاستخدام للتعامل مع وظائف متعددة، أو مشغلات (runners)، أو أسرار (secrets)؛ واستخدم الإجراء المركب لتجميع خطوات قابلة للنشر في المتجر (Marketplace).

ملخص

كلتا الميزتين تقضيان على النسخ واللصق في GitHub Actions، ولكن على مستويات مختلفة. سير العمل القابلة لإعادة الاستخدام هي ملف .GitHub/workflows يتم تفعيله بواسطة on: workflow_call؛ ويمكن أن يحتوي على وظائف متعددة، ويختار المشغلات الخاصة به، ويستقبل الأسرار، وتستدعيه من وظيفة باستخدام uses:.¹ أما الإجراء المركب فهو ملف action.yml مع runs.using: "composite"؛ حيث يجمع الخطوات في خطوة واحدة قابلة لإعادة الاستخدام، ويمكن نشره في المتجر، ولكنه لا يمكنه الوصول إلى سياق secrets أو احتواء وظائف.¹ على GitHub.com، يمكنك تداخل ما يصل إلى 10 مستويات من سير العمل واستدعاء ما يصل إلى 50 سير عمل فريدة قابلة لإعادة الاستخدام من ملف واحد.² كل ما يلي تم التحقق منه مقابل وثائق GitHub الحالية (© 2026) مع YAML قابل للنسخ واللصق.

ما ستتعلمه

• الفرق الجوهري بين سير العمل القابلة لإعادة الاستخدام والإجراء المركب
• قائمة مرجعية لاتخاذ القرار بشأن متى تستخدم كل منهما
• كيفية تعريف واستدعاء سير عمل قابلة لإعادة الاستخدام (المدخلات، الأسرار، uses:)
• كيفية كتابة واستخدام إجراء مركب (action.yml، shell:، المخرجات)
• هل يمكن للإجراء المركب استخدام الأسرار، والحل الآمن البديل
• كيفية تمرير الأسرار إلى سير العمل القابلة لإعادة الاستخدام، بما في ذلك secrets: inherit
• حدود التداخل والمصفوفة (matrix) الحالية
• كيفية إرجاع المخرجات إلى المستدعي من كل منهما
• هل يمكن لكل منهما استدعاء الآخر

ما الفرق بين سير العمل القابلة لإعادة الاستخدام والإجراء المركب؟

سير العمل القابلة لإعادة الاستخدام تعيد استخدام سير عمل كاملة (وظيفة واحدة أو أكثر وخطواتها)؛ بينما يعيد الإجراء المركب استخدام مجموعة من الخطوات التي تعمل كخطوة واحدة داخل وظيفة.¹ النتائج العملية تنبع من هذا التمييز الواحد، وتوضحها وثائق GitHub الخاصة في جدول مقارنة.¹

هناك تفصيل آخر دقيق حول الموضع: نظرًا لأن الإجراء المركب يعمل كخطوة، يمكنك وضع خطوات قبله وبعده في نفس الوظيفة. أما سير العمل القابلة لإعادة الاستخدام فيتم استدعاؤها مباشرة داخل وظيفة، لذا لا يمكنك إضافة خطوات بعد الاستدعاء في تلك الوظيفة—وبالتالي لا يمكنك استخدام GITHUB_ENV لتمرير القيم إلى خطوات لاحقة في الوظيفة المستدعية.¹

متى يجب استخدام سير عمل قابلة لإعادة الاستخدام مقابل إجراء مركب؟

اختر سير عمل قابلة لإعادة الاستخدام عندما يكون الشيء الذي تعيد استخدامه يشبه خط إنتاج (pipeline)؛ واختر إجراءً مركباً عندما يشبه الخطوة. إذا كان المنطق المعاد استخدامه يجب أن يشغل وظائف متعددة، أو يتوزع عبر مشغلات مختلفة، أو يعتمد على بيئات معينة، أو يستهلك أسراراً، فإن سير العمل القابلة لإعادة الاستخدام هي الوحيدة القادرة على التعبير عن ذلك.¹

الجأ إلى سير عمل قابلة لإعادة الاستخدام عندما تحتاج إلى أي مما يلي:

• أكثر من وظيفة واحدة، أو وظائف ذات تبعيات needs:
• وظائف تعمل على مشغلات مختلفة (على سبيل المثال، البناء على Linux، والتوقيع على macOS)
• أسرار، أو بيئات نشر، أو بوابات موافقة (approval gates)
• سجلات فورية لكل خطوة عبر خط الإنتاج بالكامل

الجأ إلى إجراء مركب عندما تحتاج إلى:

• تجميع حفنة من الخطوات المتتالية في خطوة واحدة قابلة لإعادة الاستخدام
• خطوات قبل وبعد المنطق المعاد استخدامه في نفس الوظيفة
• النشر في متجر GitHub
• البقاء على مشغل المستدعي بأقل قدر من الأعباء الإضافية

تحدد GitHub نقطة المشغل مباشرة: "إذا كان يجب تشغيل الخطوات على نوع من الآلات قد يختلف عن الآلة المختارة لوظيفة سير العمل المستدعية، فيجب عليك استخدام سير عمل قابلة لإعادة الاستخدام، وليس إجراءً مركباً."¹

كيف تقوم بإنشاء واستدعاء سير عمل قابلة لإعادة الاستخدام؟

أضف on: workflow_call إلى ملف سير العمل، وأعلن عن أي inputs و secrets، ثم استدعه من وظيفة باستخدام uses:.³ يجب أن يكون الملف القابل لإعادة الاستخدام موجوداً مباشرة في .GitHub/workflows/—المجلدات الفرعية غير مدعومة.³

# .GitHub/workflows/deploy.yml  (the reusable workflow)
name: Reusable deploy
on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
    secrets:
      deploy_token:
        required: true
    outputs:
      url:
        description: "Deployed URL"
        value: ${{ jobs.deploy.outputs.url }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    outputs:
      url: ${{ steps.ship.outputs.url }}
    steps:
      - uses: actions/checkout@v6
      - id: ship
        run: echo "url=https://${{ inputs.environment }}.example.com" >> "$GITHUB_OUTPUT"
        env:
          TOKEN: ${{ secrets.deploy_token }}

استدعه على مستوى الوظيفة. توضع المدخلات تحت with: ويجب أن يتطابق نوع بياناتها مع النوع المعلن في سير العمل المستدعى؛ وتوضع الأسرار المسماة تحت secrets:.³

# .GitHub/workflows/ci.yml  (the caller)
name: CI
on:
  push:
    branches: [main]

jobs:
  call-deploy:
    uses: octo-org/repo/.GitHub/workflows/deploy.yml@v1
    with:
      environment: staging
    secrets:
      deploy_token: ${{ secrets.DEPLOY_TOKEN }}

يمكنك الإشارة إلى الملف كـ {owner}/{repo}/.GitHub/workflows/{file}@{ref}، أو ./.GitHub/workflows/{file} لسير عمل في نفس المستودع. يمكن أن يكون {ref} عبارة عن SHA، أو وسم إصدار (release tag)، أو فرع (branch)؛ إذا تشابه اسم الوسم والفرع، فإن الوسم هو الذي يفوز، و SHA الالتزام هو الخيار الأكثر أماناً للاستقرار والأمن.³ (إجراء actions/checkout في الإصدار v6 اعتباراً من يونيو 2026.⁴)

كيف تقوم بإنشاء واستخدام إجراء مركب؟

قم بإنشاء ملف action.yml (أو action.yaml) باستخدام runs.using: "composite" وقائمة من الخطوات، ثم استدعه كخطوة باستخدام uses:.⁵ القاعدة الأساسية التي يغفل عنها المطورون: يجب أن تحدد كل خطوة run داخل الـ composite action نوع الـ shell:—لا يوجد خيار افتراضي.⁵

# .GitHub/actions/setup-build/action.yml
name: Setup and build
description: Install deps and build the project
inputs:
  node-version:
    description: Node.js version
    required: false
    default: "22"
outputs:
  artifact-path:
    description: Path to the build output
    value: ${{ steps.build.outputs.path }}
runs:
  using: composite
  steps:
    - uses: actions/setup-node@v6
      with:
        node-version: ${{ inputs.node-version }}
    - name: Install
      run: npm ci
      shell: bash
    - id: build
      run: |
        npm run build
        echo "path=dist" >> "$GITHUB_OUTPUT"
      shell: bash

استخدمها كخطوة، مع إمكانية إضافة خطوات قبلها وبعدها كما تحب:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Build via composite
        id: bp
        uses: ./.GitHub/actions/setup-build
        with:
          node-version: "22"
      - name: After
        run: echo "built at ${{ steps.bp.outputs.artifact-path }}"

قم بالإشارة إلى المدخلات باستخدام ${{ inputs.<name> }} ومخرجات الخطوات باستخدام ${{ steps.<id>.outputs.<name> }}.⁵ لاحظ أنه، على عكس الـ workflow عالي المستوى، فإن الـ composite action لا يقوم تلقائياً بتعريف مدخلاته كمتغيرات بيئة (environment variables)—لذا يجب تمريرها صراحةً عند الحاجة.⁵

هل يمكن لـ composite action استخدام الأسرار (secrets)؟

لا. سياق الـ secrets غير متاح داخل الـ composite action؛ والنهج الموثق هو تمرير السر كـ input من الـ workflow المستدعي.¹⁶ أشار فريق الـ runner في GitHub في التصميم الأصلي إلى أن دعم الأسرار في الـ composite actions تم تأجيله لتصميم مستقبلي.⁶

# المستدعي يمرر السر كمدخل (input)
      - uses: ./.GitHub/actions/deploy
        with:
          token: ${{ secrets.DEPLOY_TOKEN }}

# ملف action.yml يقرأه عبر inputs، وليس سياق secrets
inputs:
  token:
    required: true
runs:
  using: composite
  steps:
    - run: ./deploy.sh
      shell: bash
      env:
        TOKEN: ${{ inputs.token }}

إذا كنت بحاجة إلى معالجة أصلية للأسرار—أو إذا كان يجب عدم تمرير السر عبر مدخل—فاستخدم reusable workflow بدلاً من ذلك، لأن الـ reusable workflows تقبل الأسرار مباشرة.¹

كيف تمرر الأسرار إلى reusable workflow؟

قم بالتصريح عن كل سر تحت on.workflow_call.secrets، ثم مرره من المستدعي باستخدام الكلمة المفتاحية secrets:—إما بالاسم، أو جميعاً مرة واحدة باستخدام secrets: inherit.³ الكلمة المفتاحية inherit تمرر أسرار المستدعي بشكل ضمني وتعمل مع الـ workflows في نفس المؤسسة (organization) أو الشركة (enterprise).³

jobs:
  call-deploy:
    uses: ./.GitHub/workflows/deploy.yml
    with:
      environment: production
    secrets: inherit   # تمرير جميع أسرار المستدعي

هناك تنبيهان يستحقان المعرفة. أولاً، في السلسلة المتداخلة، تصل الأسرار فقط إلى الـ workflow المستدعى مباشرة: في سلسلة A ← B ← C، يتلقى الـ workflow C سر A فقط إذا قام A بتمريره إلى B ثم قام B بتمريره إلى C.³ ثانياً، on.workflow_call لا يدعم الكلمة المفتاحية environment، لذا لا يمكن تمرير الأسرار المرتبطة ببيئة معينة (environment-scoped secrets) من المستدعي.³

ما هو عدد المستويات التي يمكنك تداخل الـ reusable workflows فيها؟

على GitHub.com يمكنك ربط حد أقصى قدره عشرة مستويات من الـ workflows—المستدعي عالي المستوى بالإضافة إلى ما يصل إلى تسعة reusable workflows—ويمكنك استدعاء حد أقصى قدره 50 reusable workflow فريد من ملف workflow واحد، مع احتساب الأشجار المتداخلة.³² لا يُسمح بالحلقات (loops) في شجرة الـ workflow، ويمكن الحفاظ على الأذونات أو تقليلها فقط عبر السلسلة، ولا يمكن رفعها أبداً.³

تم رفع هذه الأرقام بمرور الوقت—لا تزال العديد من الأدلة القديمة وإجابات المنتديات تذكر الحدود السابقة وهي أربعة مستويات و20 workflow، لذا ثق بالأرقام الحالية المذكورة أعلاه.² الـ composite actions لها حدودها الخاصة—يمكنك تداخل ما يصل إلى 10 composite actions في workflow واحد.¹ وبشكل منفصل، يمكن للمصفوفة (matrix) توليد ما يصل إلى 256 وظيفة (job) لكل تشغيل workflow.⁷

# reusable workflow من مستوى متوسط يستدعي آخر من مستوى أدنى
name: Mid-level reusable
on:
  workflow_call:
jobs:
  call-another:
    uses: octo-org/repo/.GitHub/workflows/lowlevel.yml@v1

كيف تعيد المخرجات (outputs) إلى المستدعي؟

يقوم الـ reusable workflow بربط مخرجات الخطوات بمخرجات الوظيفة، ثم بمخرجات الـ workflow تحت on.workflow_call.outputs؛ ويقرأها المستدعي عبر needs.<job>.outputs.<name>.³ أما الـ composite action فيعرض المخرجات في المستوى الأعلى، ويربط كل منها بمخرج خطوة.⁵

# قراءة مخرجات reusable workflow في المستدعي
jobs:
  job1:
    uses: octo-org/repo/.GitHub/workflows/deploy.yml@v1
    with:
      environment: staging
    secrets: inherit
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo "Deployed to ${{ needs.job1.outputs.url }}"

بالنسبة لـ composite action، تقرأ الخطوة المستهلكة ${{ steps.<id>.outputs.<name> }} (كما هو موضح سابقاً في steps.bp.outputs.artifact-path). في كلتا الحالتين، يتم كتابة مخرجات الخطوات باستخدام echo "name=value" >> "$GITHUB_OUTPUT".³⁵

هل يمكن لـ composite action استدعاء reusable workflow؟

لا—يحتوي الـ composite action على خطوات (steps) وليس وظائف (jobs)، ويتم استدعاء الـ reusable workflows فقط على مستوى الوظيفة، لذا لا يمكن لـ composite action استدعاء واحد. العلاقة تعمل في الاتجاه الآخر: يمكن لوظائف الـ reusable workflow استخدام الـ composite actions مثل أي action آخر، ويمكن لـ composite action تداخل composite actions أخرى.¹

هل يمكنك استخدام مصفوفة (matrix) مع reusable workflow؟

نعم. يمكن للوظيفة التي تستخدم strategy.matrix استدعاء reusable workflow، مما ينتج عنه تشغيل واحد لكل قيمة في المصفوفة—وهو أمر مفيد لنشر (deploy) المشروع عبر بيئات متعددة.³

jobs:
  deploy-all:
    strategy:
      matrix:
        target: [dev, stage, prod]
    uses: octo-org/repo/.GitHub/workflows/deploy.yml@v1
    with:
      environment: ${{ matrix.target }}
    secrets: inherit

الخلاصة

طابق الأداة مع شكل ما تعيد استخدامه: composite action من أجل خطوة (step) قابلة لإعادة الاستخدام، و reusable workflow من أجل خط إنتاج (pipeline) قابل لإعادة الاستخدام. إذا كنت بحاجة إلى وظائف، أو runners متعددة، أو بيئات، أو أسرار أصلية، فهي reusable workflow؛ إذا كنت تريد حزمة خطوات خفيفة الوزن وقابلة للنشر في Marketplace وتعيش داخل وظيفة موجودة، فهي composite action.¹

من هنا، قم بربط خط الإنتاج القابل لإعادة الاستخدام بعمليات نشر حقيقية باستخدام عمليات نشر GitHub Actions بدون مفاتيح إلى AWS باستخدام OIDC و Terraform أو GCP Workload Identity Federation، واجعل الـ CI القابل لإعادة الاستخدام يفشل بوضوح مع حدود تغطية Vitest التي تكسر البناء.