تُمثّل هذه الحزمة حلاً متكاملاً وشاملاً لأتمتة عملية النشر على GitHub Pages. تتضمن الحزمة مجموعة متنوعة من سير العمل (Workflows) التي تُلبي احتياجات مختلفة، بدءاً من النشر البسيط وحتى العمليات المعقدة التي تشمل الاختبارات الأمنية والجودة والإشعارات المتعددة.
تم تصميم هذه الحزمة لتكون سهلة الاستخدام ومتوافقة مع معظم أنواع المشاريع静态ية. سواء كنت مطوراً مبتدئاً تبحث عن طريقة بسيطة لنشر موقعك، أو محترفاً يحتاج إلى نظام نشر متقدم مع جميع الميزات الأمنية، ستجد في هذه الحزمة ما يناسب احتياجاتك.
تشمل الحزمة أربعة ملفات رئيسية هي: سير العمل المتكامل الذي يحتوي على جميع الميزات، سير العمل البسيط للمشاريع الصغيرة، سير عمل الاختبارات لفحص الجودة والأمان، وسير عمل Jekyll لمشاريع Jekyll. بالإضافة إلى ذلك، تتضمن الحزمة وثائق شاملة وأمثلة على الإعدادات والجداول التوضيحية.
🚀 بداية سريعة
المتطلبات الأساسية
قبل البدء في استخدام هذه الحزمة، تأكد من توفر المتطلبات التالية:
حساب على GitHub مع صلاحية إنشاء المستودعات وتفعيل GitHub Pages.
مستودع يحتوي على ملفات الموقع (HTML، CSS، JavaScript، إلخ).
معرفة أساسية بـ Git وGitHub Actions (اختياري).
ملف package.json إذا كان مشروعك يستخدم Node.js (اختياري).
خطوات التثبيت
الخطوة الأولى هي نسخ الحزمة إلى مستودعك. يمكنك القيام بذلك عن طريق إنشاء المجلد .github/workflows/ في جذر مستودعك إذا لم يكن موجوداً، ثم نسخ الملفات المطلوبة من هذه الحزمة إلى داخل هذا المجلد. بعد ذلك، ادفع التغييرات إلى GitHub وانتظر حتى يتم تشغيل سير العمل تلقائياً.
للحصول على أفضل النتائج، يُنصح بالبدء بسير العمل البسيط (simple-deploy.yml) للتأكد من أن الإعدادات الأساسية تعمل بشكل صحيح. ثم يمكنك الترقية إلى سير العمل المتكامل (complete-deployment.yml) عندما تحتاج إلى ميزات إضافية.
📁 محتويات الحزمة
1. سير العمل المتكامل (complete-deployment.yml)
هذا هو الملف الرئيسي والأكثر شمولاً في الحزمة. يتضمن الميزات التالية:
التحقق المبدئي (Pre-flight Check) يقوم هذا المكون بفحص التغييرات قبل البدء في عملية النشر. إذا لم تكن هناك تغييرات في ملفات البناء (مثل HTML وCSS وJS)، يتم إنهاء العملية تلقائياً لتوفير الوقت والموارد. كما يحدد بيئة النشر المناسبة بناءً على الفرع.
فحص الأمان (Security Scan) يشمل هذا المكون عدة فحوصات أمنية مهمة. أولاً، يفحص المستودع عن أسرار ومفاتيح قد تكون عُرضت بالخطأ في الكود. ثانياً، يفحص ثغرات الحزم (Dependencies) باستخدام npm audit. ثالثاً، يفحص المحتوى المختلط (HTTP على HTTPS). وأخيراً، يتحقق من صلاحيات الملفات الحساسة.
الاختبارات الآلية (Automated Tests) يتضمن هذا المكون فحوصات جودة متعددة. فحص إمكانية الوصول (Accessibility) يتحقق من وجود سمات alt على الصور وهيكل العناوين الصحيح ووجود labels للنماذج. فحص الروابط يتحقق من سلامة الروابط الداخلية. وفحص الأداء يقيس حجم الملفات ويحسب درجة أداء.
بناء المشروع (Build) يقوم هذا المكون ببناء المشروع وتجهيزه للنشر. يشمل ذلك تثبيت التبعيات، إنشاء معلومات الإصدار، تنفيذ أوامر البناء، وحساب معلومات البناء (الوقت والحجم).
النشر المتعدد البيئات يدعم النظام ثلاث بيئات نشر مختلفة. بيئة Production للفرع الرئيسي، بيئة Staging لفرع develop، وبيئة Development للفروع الأخرى. يمكن أيضاً تشغيل أي بيئة يدوياً من خلال workflow_dispatch.
نظام الإشعارات يرسل إشعارات إلى Discord وSlack عند نجاح النشر. يتطلب ذلك إعداد متغيرات البيئة المناسبة (DISCORD_WEBHOOK_URL وSLACK_WEBHOOK_URL).
التقارير والإحصائيات يولد تقارير مفصلة بعد كل عملية نشر تتضمن معلومات النشر وإحصائيات البناء والروابط المفيدة.
نظام التراجع في حالة فشل النشر على الفرع الرئيسي، يقوم النظام تلقائياً بإنشاء Issue في GitHub يوثق تفاصيل الفشل ويقدم خطوات للتراجع.
2. سير العمل البسيط (simple-deploy.yml)
هذا الملف مناسب للمشاريع الصغيرة والبسيطة التي لا تحتاج إلى ميزات متقدمة. يقوم فقط بنشر الملفات الموجودة في المستودع إلى GitHub Pages دون أي فحوصات أو اختبارات.
الميزات الرئيسية:
نشر تلقائي عند الدفع لأي فرع.
نشر يدوي متاح.
إلغاء العمليات السابقة تلقائياً.
مناسب للمشاريع التي لا تستخدم Node.js.
مثال على الاستخدام المناسب:
صفحات HTML ثابتة بسيطة.
وثائق Markdown بسيطة.
ملفات تصميم أو ملف شخصي.
3. سير عمل الاختبارات (testing.yml)
هذا الملف متخصص في فحوصات الجودة والأمان ولا يقوم بالنشر. يمكن استخدامه لعمليات فحص دورية أو عند تقديم طلبات السحب (Pull Requests).
الفحوصات المتضمنة:
فحص إمكانية الوصول (Accessibility).
فحص الروابط الداخلية.
فحص الأداء وحجم الملفات.
فحص صحة HTML.
فحص الأسرار والمفاتيح.
فحص المحتوى المختلط.
المميزات:
يعمل عند تقديم طلبات السحب.
يولد تقارير مفصلة.
لا يقوم بالنشر.
4. سير عمل Jekyll (jekyll-deploy.yml)
هذا الملف متخصص في نشر مواقع Jekyll. يقوم ببناء الموقع باستخدام Jekyll ثم نشره.
الميزات:
إعداد Ruby والتبعيات تلقائياً.
بناء Jekyll مع التخزين المؤقت.
نشر مباشر إلى GitHub Pages.
مناسب للمواقع المبنية على Jekyll.
⚙️ الإعداد والتخصيص
إعداد الإشعارات
لتفعيل نظام الإشعارات، تحتاج إلى إضافة الأسرار التالية إلى إعدادات المستودع:
يمكنك إضافة هذه الأسرار من خلال: اذهب إلى Settings، ثم Secrets and variables، ثم Actions، ثم اضغط على New repository secret.
تخصيص الاختبارات
يمكنك تخصيص الاختبارات بتعديل المتغيرات البيئية في بداية كل ملف. على سبيل المثال، لتغيير مستوى أمان فحص الـ dependencies، ابحث عن SECURITY_LEVEL وقم بتغييره من moderate إلى high أو critical.
تخصيص أنواع الملفات للفحص
في سير العمل المتكامل، يمكنك تعديل أنماط الملفات التي تستوجب إعادة البناء. ابحث عن قسم paths-ignore وقم بإضافة أو إزالة أنماط الملفات حسب احتياجاتك.
إعداد Node.js
إذا كان مشروعك يستخدم Node.js، يمكنك تخصيص إصدار Node.js من خلال المتغير NODE_VERSION. الإصدار الافتراضي هو 20، لكن يمكنك تغييره إلى 18 أو 16 إذا كان مشروعك يتطلب ذلك.
📊 الجداول التوضيحية
مقارنة سير العمل
الميزة
بسيط
متكامل
اختبارات
Jekyll
النشر التلقائي
✅
✅
❌
✅
فحص التغييرات
❌
✅
✅
❌
فحص الأمان
❌
✅
✅
❌
اختبارات الجودة
❌
✅
✅
❌
نظام الإشعارات
❌
✅
❌
❌
التقارير
❌
✅
✅
❌
التراجع
❌
✅
❌
❌
Jekyll مدمج
❌
❌
❌
✅
متطلبات الأنظمة
المتطلب
الحد الأدنى
الموصى به
GitHub Actions
Ubuntu latest
Ubuntu latest
Ruby (لـ Jekyll)
3.0
3.1+
Node.js
16
20
التخزين المؤقت
500MB
1GB
🔧 حل المشاكل الشائعة
المشكلة الأولى: عدم تشغيل سير العمل
إذا لم يتم تشغيل سير العمل بعد دفعه، تأكد من أن الملف موجود في المسار الصحيح .github/workflows/filename.yml. تأكد أيضاً من أن اسم الملف ينتهي بـ .yml وليس .yaml. تحقق من صحة بناء YAML باستخدام محلل YAML.
المشكلة الثانية: فشل النشر بسبب الصلاحيات
إذا فشل النشر بسبب مشاكل في الصلاحيات، تأكد من أن GitHub Pages مفعل من إعدادات المستودع. تحقق من أن الصلاحيات في قسم permissions صحيحة. تأكد من أن المستودع عام (public) إذا كنت تستخدم حساباً مجانياً.
المشكلة الثالثة: مشاكل في بناء Node.js
إذا فشل بناء Node.js، تأكد من وجود ملف package.json صحيح في المستودع. تحقق من أن إصدار Node.js المتاح متوافق مع إصدار package.json. تأكد من تثبيت جميع التبعيات باستخدام npm ci بدلاً من npm install.
المشكلة الرابعة: مشاكل Jekyll
إذا فشل بناء Jekyll، تأكد من وجود ملف _config.yml صحيح. تحقق من أن جميع الإضافات المستخدمة مدعومة من GitHub Pages. راجع سجلات البناء للأخطاء المحددة.
📝 أمثلة على الإعدادات
مثال على package.json للنشر
json
1{2"name":"my-website",3"version":"1.0.0",4"description":"My personal website",5"scripts":{6"build":"npm run build:css && npm run build:js",7"build:css":"postcss src/css/style.css -o dist/css/style.css",8"build:js":"esbuild src/js/app.js --bundle --outfile=dist/js/app.js",9"test":"echo 'No tests specified'"10},11"devDependencies":{12"postcss":"^8.4.0",13"esbuild":"^0.19.0"14}15}
مثال على _config.yml لـ Jekyll
yaml
1title: موقعي الشخصي
2description: وصف الموقع
3baseurl:""4url:"https://username.github.io"5plugins:6- jekyll-feed
7- jekyll-seo-tag
89markdown: kramdown
10theme: minima
