GitHub Actions: بناء خطوط CI/CD تحمي main وتنشر بثقة

ماذا ستخرج به من هذا المقال؟

خط النشر ليس ملفًا تُكتب فيه أوامر ثم تُتجاهل، بل نظام قرار يقرر نيابة عن الفريق متى يُعتمد الدمج ومتى يُمنع، ومتى تصل الشيفرة إلى العميل ومتى تُعزل. GitHub Actions يمنحك هذا النظام داخل المستودع نفسه: سير بالخطوات، ومشغّلات تشغيل، وأسرار محمية، ومصفوفات بيئات. هذا المقال يبني خطوط أنابيب كاملة من المثال الأول إلى بنية تنمو مع مشروعك.

ستتعلم كيف تصمم الوظائف (jobs) صغيرة مسؤولة عن مرحلة واحدة، وكيف تمنع تسرب الأسرار من السجلات، وكيف تتحكم في التشغيل بالفلاتر (paths وbranches وworkflow_dispatch)، وكيف تؤثر على البيئات والمصادقات بين الخطوات. النتيجة: دمج لا يصل إلى main إلا ناجحًا، ونشر لا يصل إلى العميل إلا مفحوصًا.

التصميم قبل الكود: ماذا يفعل خط أنابيبك؟

قبل كتابة أول سطر YAML اسأل: ما الذي يجب أن يُمنع من الوصول إلى الفرع الرئيسي؟ وما الذي يجب أن يحدث قبل كل إصدار؟ خط الأنابيب الجيد هو ترجمة لسياسة الفريق لا ترجمة لأوامر. رتّب حاجزك على أربع مراحل:

• التشفير والثوابت: تحقق من الأسلوب، وأنواع غير قابلة للكسر، وأنماط ترميز موحدة.


• الاختبارات: وحدة، ثم تكامل، ثم نهاية-إلى-نهاية في المدى الذي يسمح زمنه.


• البناء: أنتج النسخ الصالح للنشر كبقايا (artifacts) قابلة للنقل.


• النشر: ادفع النسخة إلى البيئة المستهدفة ببوابات تحكم.

أول سير عمل: الشفرة المعتمدة

الملف يعيش في .github/workflows/ci.yml. المشغل (trigger) الأهم لتجنّب الفوضى هو pull_request وpush إلى فروع محددة:

name: CI

on:

  pull_request:

  push:

    branches: [main]



jobs:

  lint-and-test:

    runs-on: ubuntu-latest

    strategy:

      matrix:

        php-version: ['8.2', '8.3']

    steps:

      - uses: actions/checkout@v4

      - uses: shivammathur/setup-php@v2

        with:

          php-version: ${{ matrix.php-version }}

      - run: composer install --no-interaction --prefer-dist

      - run: php artisan test --testsuite=unit

لاحظ مصفوفة إصدارات PHP: الاختبار على إصدارين يمنع التوافق بطريق الصدفة. هذا النمط (المصفوفة) هو أول ما تضيفه بعد أن ترى المشروع يخضر.

الأوراق النقدية: الفلاتر عندما لا تحتاج تشغيل كل شيء

لا تدع تغيير مستند يتبني عشر دقائق. ركّز المشغل بفلاتر المسارات حتى تشغّل الوظائف ذات الصلة فقط:

on:

  pull_request:

    paths:

      - 'app/**'

      - 'tests/**'

      - 'composer.lock'

      - 'database/**'

وبالمقابل، هناك أحداث تحتاج تشغيلًا يدويًا من واجهة GitHub دائمًا: workflow_dispatch تحويل للنشر اليدوي، وschedule لاختبارات ليلية مخططة. اجمع بينها بحذر: الفلاتر الصارمة تدخل الفريق عادة التأكد اليدوي، وهو ما تريد تجنبه.

الأسرار: مفتاح لا يظهر أبدًا

كل ما تحتاجه الصورة هو أسرار (secrets) في إعداد الإعدادات — مجموعة البيئة وأنواعها. القاعدة: لا قيمة حساسة ضمن YAML، ولا سجل يُطبع فيها:

env:

  DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}

steps:

  - run: |

      echo "::add-mask::$DEPLOY_KEY"

      echo "Deploying to production…"

صُرف أيضًا عن المستوى: الأسرار يجب أن تخص البيئة الأقل صلاحية — سر اختبارات لبيئة تجريبية، وسر نشر منفصل للإنتاج — لئلا يصل من يسرق مفتاح اختبار إلى سلسلة إنتاج كاملة.

من البناء إلى النشر: الروابط والبوابات

النشر يتطلب وظائف تتبع بعضها بنجاح: needs يربطها، وenvironment يضيف بوابة مراجعة أو حماية للمطارح (من يحق له النشر للإنتاج؟). أنتج نسخة البناء في خطوة upload-artifact وأعد استخدامها في خطوة النشر بدل إعادة البناء مرتين.

build:

  runs-on: ubuntu-latest

  steps:

    - name: Build release

      run: php artisan build

    - name: Archive

      uses: actions/upload-artifact@v4

      with: { name: release, path: 'dist/' }



deploy-production:

  needs: [testing, build]

  environment: production

  runs-on: ubuntu-latest

  steps:

    - uses: actions/download-artifact@v4

      with: { name: release, path: 'dist/' }

    - name: Deploy

      run: ./scripts/deploy.sh ${{ github.sha }}

الخطأ الذي يعلّم: التصحيح والسجل

أولى أدوات تصحيح السير العمل هي عرض السجلات المنظمة لكل خطوة، ثم debug المدعومة لمنهجية الذهن، ثم إعادة تشغيل فاشلة خطوة بعد خطوة. والفحص الحقيقي أن تفهم منطق الفشل: اختبار فاشل معناه شيفرة غير صالحة، وخطوة نشر فاشلة معناه تكوين مضلل أو صلاحية. لا تكتب استثناءات («الاختبار الفاشل هذا مؤقت») دون وثيقة زمنية واضحة.

قائمة تحقق سير العمل

• كل وظيفة صغيرة ونتيجتها قابلة للقياس، والترتيب واضح عبر needs.


• الفلاتر تحدّ التشغيل للمسارات ذات الصلة ولا تمنع تشغيلاً ضروريًا.


• الأسرار في المستودع لا في السجلات، والحد الأدنى من الصلاحيات لكل بيئة.


• البناء ينتج artifact ويُعاد استخدامه في النشر لا يُعاد بناؤه.


• بيئة الإنتاج محمية ببوابة مراجعة أو نافذة زمنية مُقننة.


• تصحيح فشل الوظائف مبني على فهم السبب لا على الاستثناءات الشفوية.

الأسئلة الشائعة

لماذا يتحول سير العمل إلى بطء شديد؟

لأن كل شيء يشغّل كل شيء. أضف فلاتر المسارات، أعد استخدام artifacts، وافصل اختبارات بطيئة (نهاية-إلى-نهاية) إلى وظيفة تُشغَّل على الدمج فقط أو يدويًا.

هل الأسرار آمنة في Actions؟

مشفرة ولا تظهر للمشغّلين غير المصرح لهم، لكن الأمان يبدأ من إعدادات النشر: أصل محدود، وإذن متدرج، ولوحة مسح للأحداث السلبية في سجل النشاط.

ماذا لو كانت السراقة في PR من فرع خارج؟

لا تكشف الأسرار إلّا بمستوى pull_request بعد دمج وليس ضمن pull_request_target إلا وحدة موقوفة — افحص أي استخدام لـ pull_request_target بمراجعة خاصة.

الخلاصة

الخطوة التالية

بعد أن بنيت آلية تعلن «الصالح للنشر»، يبقى الجزء البشري الذي يقرر الجودة: مراجعة الكود. المقال القادم يحوّل مراجعة PR من إجراء شكلي إلى حاجز قرار حقيقي.

flowchart LR

    A["إيداع الشيفرة"]

    B["اختبارات آلية"]

    C["بناء نسخة"]

    D["نشر متدرج"]

    E["مراقبة وتراجع"]

    A --> B

    B --> C

    C --> D

    D --> E