GitHub Actions بعمق

الأسرار والبيئات والموافقات في GitHub Actions

18 دقيقة الدرس 7 من 30

الأسرار والبيئات والموافقات في GitHub Actions

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

الأسرار: النطاق والأولوية

لكل سر في GitHub Actions نطاق. تشكّل النطاقات هرمًا، ويُقدَّم النطاق الأكثر تحديدًا عند تعارض الأسماء:

أسرار المنظمة — مرئية لجميع المستودعات (أو مستودعات مختارة) في المنظمة. يكفي تدوير مفتاح API جهة خارجية مرة واحدة بدلًا من 200 مستودع.
أسرار المستودع — مقتصرة على مستودع واحد؛ مناسبة للرموز الخاصة بالمستودع كحساب خدمة Docker Hub.
أسرار البيئة — مقتصرة على بيئة محددة (production، staging). تُحقن فقط عندما يستهدف العمل تلك البيئة. العمل الذي يستهدف staging لا يرى أسرار production أبدًا — حتى لو تشاركت البيئتان اسم سر.

تتجاوز أسرار البيئة أسرار المستودع التي تحمل الاسم ذاته. استخدم هذا بوعي: عرّف AWS_ROLE_ARN ذا صلاحيات محدودة على مستوى المستودع، وآخر ذا صلاحيات عالية على مستوى بيئة production.

ارجع إلى الأسرار عبر سياق secrets: ${{ secrets.MY_SECRET }}. يُخفي GitHub القيمة الحرفية في جميع مخرجات السجلات — لكن احذر من التسريب عبر Base64 أو ترميز URL (خطأ شائع). لا يمكنك استرداد قيم الأسرار عبر API؛ إن فقدت سرًا، دوّره.

البيئات: نموذج بوابة النشر

البيئة هي هدف نشر مسمّى يحمل أسراره وإعداداته المتغيرة وقواعد حمايته الخاصة. فكّر فيها على أنها حد الإنفاذ بين "الكود المدمج" و"الكود الذي يعمل في الإنتاج".

تُعلن البيئة على مستوى العمل:

jobs:
  deploy-production:
    runs-on: ubuntu-24.04
    environment:
      name: production
      url: https://app.example.com   # يظهر في واجهة الجدول الزمني للنشر
    steps:
      - name: Deploy
        run: ./scripts/deploy.sh
        env:
          AWS_ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }}   # سر البيئة
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

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

قواعد الحماية بالتفصيل

انتقل إلى Settings → Environments → [اسم البيئة] لتهيئة القواعد. أربع قواعد أساسية في الإنتاج:

1. المراجعون المطلوبون

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

استخدم فريق GitHub (مثل @my-org/release-engineering) بدلًا من أفراد محددين للمراجعين المطلوبين. الفرق تتحمل تغييرات الموظفين، وأي عضو في الفريق يمكنه الموافقة — مما يمنحك تغطية دون إنشاء نقطة إخفاق واحدة.

2. مؤقت الانتظار

تأخير (0–43,200 دقيقة) يُدرج قبل أن تصبح البيئة نشطة. استخدم هذا كوقت نضج إلزامي: يمكن لبيئة الاختبار استيعاب انتظار 10 دقائق بينما تعمل اختبارات الدخان تلقائيًا بعد النشر على الاختبار، قبل أن يُسمح حتى للإنتاج بالبدء. هذا ليس بديلًا عن الاختبار — بل هو دفاع متعمق.

3. فروع وعلامات النشر

حدد أي المراجع يمكنها النشر إلى هذه البيئة. الخيارات:

جميع الفروع — بدون قيود (مناسب لـ dev، خطير لـ production).
الفروع المحمية فقط — فقط الفروع ذات قواعد حماية الفروع يمكنها النشر. هذا يعني ضمنيًا مراجعة طلبات السحب واجتياز فحوصات الحالة.
فروع وعلامات مختارة — أنماط صريحة مثل main أو release/* أو v[0-9]*.[0-9]*.[0-9]*. هذا هو المعيار في الشركات الكبرى: الإنتاج يقبل فقط العلامات المطابقة لنمط semver، مما يُلزم بأن كل نشر إنتاج هو إصدار موسوم.

4. منع المراجعة الذاتية

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

أنبوب إنتاج يشتمل على بوابة بيئة الاختبار تليها بوابة موافقة بشرية إلزامية قبل حقن أي أسرار إنتاج.

سير عمل كامل مع البيئات

يربط سير العمل التالي البناء ونشر الاختبار ونشر الإنتاج مع نطاق مناسب. اقرأ سلسلة needs: ينفَّذ عمل الاختبار فقط بعد نجاح الاختبارات؛ وينفَّذ عمل الإنتاج فقط بعد نجاح الاختبار وموافقة المراجع.

name: Deploy Pipeline

on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'   # تصل الإنتاج فقط الإصدارات الموسومة

jobs:
  build-and-test:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - run: npm ci
      - run: npm test
      - name: Build artifact
        run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  deploy-staging:
    needs: build-and-test
    runs-on: ubuntu-24.04
    environment:
      name: staging
      url: https://staging.example.com
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
      - name: Deploy to staging
        run: ./scripts/deploy.sh staging
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}   # سر بيئة الاختبار

  deploy-production:
    needs: deploy-staging
    runs-on: ubuntu-24.04
    environment:
      name: production
      url: https://app.example.com
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
      - name: Deploy to production
        run: ./scripts/deploy.sh production
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}   # سر بيئة الإنتاج (قيمة مختلفة)
          DATADOG_API_KEY: ${{ secrets.DATADOG_API_KEY }}

لا تضع environment: production على أعمال البناء أو الاختبار. إن فعلت، تُطلق بوابة الموافقة قبل تشغيل الاختبارات — يوافق المراجعون على بناء قد لا يُكمل حتى، وتُحمَّل أسرار الإنتاج في عمل لا يحتاجها. إعلان البيئة ينتمي فقط إلى العمل الذي ينشر فعليًا.

قواعد الحماية المخصصة للنشر (تطبيقات GitHub)

منذ 2023، يدعم GitHub قواعد الحماية المخصصة للنشر عبر تطبيقات GitHub. بدلًا من توقف GitHub وانتظار الإنسان، يستدعي webhook على تطبيقك الذي يطبق منطقه الخاص ثم يستدعي GitHub API للموافقة أو الرفض. تستخدم الفرق الكبيرة هذا لربط:

التحقق من تذكرة لجنة مستشاري التغيير (CAB) — بدون تذكرة، لا نشر.
فحوصات جاهزية علامات الميزات — تأكيد تعطيل العلامة قبل وصول الكود الذي يستخدمها.
تطبيق ساعات العمل — رفض النشر تلقائيًا خارج النافذة المسموح بها، أو تصعيده إلى مراجع مناوبة.
فحوصات صحة Canary — استعلام منصة المراقبة ورفض ترقية الإنتاج إن كانت معدلات الخطأ مرتفعة.

لمعظم الفرق، المراجعون المطلوبون بالإضافة إلى قواعد الفروع/العلامات كافيان ولا يتطلبان أي كود. استثمر في قواعد الحماية المخصصة فقط عند الحاجة إلى إنفاذ آلي بالسياسة كالكود لا يمكن لبوابة بشرية توفيره بسرعة كافية (مثل قرار التراجع التلقائي لـ Canary في 30 ثانية).

أوضاع الفشل الشائعة

المراجع هو من أطلق التشغيل. مع تفعيل منع المراجعة الذاتية، إن كان المراجع الوحيد المهيّأ هو المهندس الذي دفع العلامة، يتوقف النشر. اضبط دائمًا فريقًا بعضوين على الأقل، أو راجعًا احتياطيًا.

تعارض اسم السر عبر النطاقات. يضيف مطور DATABASE_URL على مستوى المستودع يشير إلى الاختبار، غير مدرك أن بيئة production لديها DATABASE_URL خاص بها. تلتقط أعمال الاختبار القيمة على مستوى المستودع بشكل صحيح. كل شيء يبدو جيدًا — حتى يحذف شخص ما سر البيئة، وفجأة يبدأ نشر الإنتاج في استخدام رابط قاعدة بيانات الاختبار. راجع وثّق هرمية الأسرار لديك.

انتهاء مهلة الموافقة. يحتفظ GitHub بالنشر المعلق لمدة 30 يومًا ثم يُنهيه. إن كان مراجعك في إجازة ولا يوجد احتياطي، تنتهي صلاحية الإصدار بصمت. اضبط تذكيرات التقويم أو إشعارات Slack لتنبيه الفريق عند انتظار نشر للموافقة.

تجاوز البوابة عبر workflow_dispatch. زناد workflow_dispatch بفرع غير موجود في قائمة الفروع المسموح بها للبيئة سيضرب قواعد الحماية رغم ذلك. لكن إن أنشأ شخص ما سير عمل بديل يتخطى عمل deploy-staging ويذهب مباشرة إلى deploy-production، تُطلق البوابة رغم ذلك — لأن قواعد الحماية هي لكل بيئة، وليس لكل ملف سير عمل. هذا هو النموذج الذهني الصحيح: البوابة على البيئة، وليس على ملف سير العمل.