CI/CD

تستخدم جميع مستودعات المنظومة GitHub Actions. وتشرح هذه الصفحة الأنماط والاصطلاحات المشتركة.

المبادئ الأساسية

1. الفحص عند طلب الدمج، والنشر عند main. يشغّل طلبُ الدمج البناءَ والاختبارات ولا ينشر شيئًا. ولا يبدأ النشر إلّا بعد الدمج في main.
2. لا يُبنى إلّا ما تغيّر. يحدّد paths-filter الأجزاء المتغيّرة، فلا يُعاد بناء سوى تلك الخدمات.
3. لا نشر متزامن. تضع مجموعة concurrency عمليات نشر الإنتاج في طابور، فلا تتزامن أبدًا.
4. الأسرار في GitHub Secrets وحدها. ولا تُكتب في ملف سير العمل قطّ.

الشكل المعتاد لسير العمل

name: deploy

on:
  push:
    branches: [main]
    paths:
      - 'backend/**'
      - 'frontend/**'
      - '.github/workflows/deploy.yml'
  workflow_dispatch:          # إمكان التشغيل يدويًا

concurrency:
  group: deploy-production
  cancel-in-progress: false   # لا تقطع النشر في منتصفه

‏cancel-in-progress: false أمرٌ مهم

قد يترك النشرُ المقطوع في منتصفه حالةً ناقصة: الحاوية الجديدة لم تُشغَّل والقديمة أُطفئت. فينبغي ترك النشر يبلغ نهايته، ووضع التالي في الطابور.

مرحلة الفحص (طلب الدمج)

الفحص	ما يفعله
البناء	هل تُترجَم الشيفرة
اختبارات الوحدة	منطق الأعمال
اختبارات التكامل	‏testcontainers — ‏PostgreSQL/Redis حقيقيان
Lint	أسلوب الشيفرة
بناء صارم للوثائق	يكشف الروابط المكسورة والملفات المفقودة

الفحص الصارم للوثائق

يُبنى MkDocs بوضع --strict. وفي هذا الوضع تصير التحذيرات أخطاءً:

• الروابط الداخلية المكسورة،
• الملفات المذكورة في nav وغير الموجودة،
• الملفات الموجودة وغير المدرَجة في nav.

وبذلك لا يبلغ خللُ الوثائق بيئةَ الإنتاج.

مرحلة النشر

تجري بالاتّصال بالمضيف عبر SSH. والأسرار اللازمة (بالتسمية الشائعة):

السرّ	المعنى
DEPLOY_HOST	عنوان الخادم
DEPLOY_USER	مستخدم SSH
DEPLOY_SSH_KEY	المفتاح الخاص
DEPLOY_PORT	منفذ SSH (اختياري، والافتراضي 22)
DEPLOY_PATH	المسار على المضيف

مفتاح SSH لا كلمة مرور

يَستعمل النشرُ مفتاح SSH لا كلمةَ مرور. فالمفتاح يسهل إبطاله، واحتمال ظهوره سهوًا في السجلّات أقل، ويمكن تدويره من دون إعادة توزيعه على جمعٍ من الناس.

البناء الجزئي

في المستودع الأحادي لا ينبغي أن يفرض تغييرٌ واحد إعادةَ بناء كل الخدمات:

- uses: dorny/paths-filter@v3
  id: filter
  with:
    filters: |
      backend: 'backend/**'
      frontend: 'frontend/**'
      edge: 'nginx/**'

ثم لا يُعاد بناء سوى الخدمات المتغيّرة. وإن كان المتغيّر هو الحافّة (nginx) فلا إعادة بناء كاملة، بل مزامنة للإعداد + nginx -t + إعادة تحميل فحسب.

نشر إعدادات الحافّة

يُدار conf.d الخاص بـ edge nginx عبر git. وتسلسل النشر:

1. مزامنة المستودع على المضيف بـ git fetch && git reset --hard،
2. ‏docker exec <nginx> nginx -t — للتحقّق من الإعداد،
3. وعند النجاح nginx -s reload.

لا تتخطَّ nginx -t

إعادة التحميل بإعدادٍ خاطئ تجعل nginx يعجز عن العودة للعمل — وعندها تسقط جميع النطاقات. فيجب أن يُنفَّذ nginx -t قبل إعادة التحميل، وأن يوقف الفشلُ عمليةَ النشر.

المُنفِّذات ذاتية الاستضافة

تستعمل عمليات بناء iOS وWindows (توقيع الشيفرة، والتوثيق، وحزم MSIX) مُنفِّذات macOS / Windows ذاتية الاستضافة. فهي تحتاج أدواتٍ وشهاداتٍ خاصة بالمنصّة، ولذلك لا تعمل على مُنفِّذات سحابية.

الإصدارات والتراجع

• الصور موسومة. ويمكن بمتغيّر <SVC>_IMAGE_TAG على المضيف تثبيتُ إصدار بعينه.
• أمّا المواقع الساكنة فيُعاد فكّ أرشيف البناء السابق.

التكامل والنشر في هذا المستودع

لمستودع docs-gerege-mn سيرا عمل اثنان:

سير العمل	متى	ماذا يفعل
ci.yml	طلب الدمج + الدفع إلى main	بناء MkDocs بوضع --strict؛ ويترك أثرًا (artifact)
deploy.yml	الدفع إلى main + يدويًا	بناء ← نسخ ← تحديث الحاوية ← تثبيت مضيف الحافّة الافتراضي ← فحص الموقع الحيّ

للتفاصيل راجع منصّة هذه الوثائق.