Github-Action-Tutorial — مسار تعلّم عملي لـ GitHub Actions

مستودع تعليمي شخصي — محاولة منظّمة لفهم GitHub Actions بعمق يكفي لتطبيقها على مشاريع كبيرة لا على أمثلة معزولة.

نظرة عامة

Github-Action-Tutorial دفتر عمل أكثر منه مرجع. كل موضوع فيه مرتبط بملف workflow حقيقي داخل .github/workflows/، أي أن كل ملاحظة مكتوبة قابلة للتشغيل والتحقّق منها على منصّة GitHub مباشرة.

المنهج المعلن في المستودع صريح:

learn basic only and start doing on a real project later everything will come

وأبسط مثال في المسار يوضّح الهيكل الكامل لـ workflow في بضع أسطر:

name: simple
on: [push]
jobs:
  build-projects:
    runs-on: ubuntu-latest
    steps:
      - name: echo string
        run: |
          echo "Hello World 1"
          echo "Hello World 2"

المشكلة

تعلّم أدوات الأتمتة يفشل عادةً لأسباب لا علاقة لها بصعوبة الأداة نفسها:

1. الوثائق الرسمية مرجع لا مسار. هي منظّمة حسب الخاصية لا حسب ترتيب التعلّم، فيصعب معرفة ما يجب إتقانه أولاً.
2. الأمثلة المعزولة تُنسى. مقطع YAML في ملف ملاحظات لا يثبت أنه يعمل، ولا يكشف أخطاء المسافات والمستويات التي تقتل workflow كاملاً.
3. دورة التغذية الراجعة بطيئة. لا يمكن تشغيل workflow محلياً بسهولة؛ كل تجربة تحتاج دفعة إلى المستودع وانتظار المُنفّذ.

التخطيط

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

المرحلة	ما تغطيه	الملف المرجعي
المقدّمة	بنية workflow، الأحداث، jobs، runs-on، steps	simple.yml
الأحداث والمرشّحات	الجدولة، الأحداث الخارجية، الترشيح بـ branches و tags و paths	actions.yml
البيئة والأسرار	متغيّرات البيئة، secrets، تشفير الملفات وفكّه	—
الاستراتيجيات	التوازي، تعدّد أنظمة التشغيل والإصدارات، التنفيذ داخل حاوية	—
التطبيق	بناء workflow لـ CI/CD، ثم كتابة action خاصة	—

وضع تقدير زمني لكل مرحلة (المقدّمة وحدها 1.5 hours) جعل المسار قابلاً للمتابعة بدل أن يكون قائمة رغبات مفتوحة.

القرارات المعمارية

الملاحظة تشير إلى ملف لا تستبدله. البديل المعتاد هو تجميع كل الأمثلة داخل README واحد طويل، لكنه ينتج أمثلة لم تُشغّل قطّ. ربط كل بند بملف داخل .github/workflows/ يعني أن GitHub نفسه هو مُدقّق صحة الملاحظات.

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

أهداف معلنة قبل المحتوى. يبدأ التوثيق بقسم Target يحدّد أربع غايات: أتمتة البناء والنشر، وCI/CD، وأتمتة طلبات الدمج، وأتمتة مراجعتها. وجود الهدف قبل المادة يحسم ما يستحقّ الوقت وما يُترك.

التنفيذ

المسار يتدرّج من بنية workflow إلى بناء action مخصّصة:

• البنية الأساسية — name وon وjobs وruns-on وsteps، مع شرح متى يلزم الرمز | لكتابة أوامر متعددة الأسطر داخل run.
• الربط بين المهام — needs لفرض ترتيب بين jobs، وuses لاستدعاء actions جاهزة، وwith لتمرير المعاملات إليها.
• التحكم في التشغيل — أنواع الأحداث وفروعها، والتشغيل المشروط، والترشيح بـ tags وbranches وpaths لتجنّب تشغيل كل شيء عند كل تعديل.
• الأسرار — متغيّرات البيئة وsecrets والتعامل مع ملفات مشفّرة داخل المستودع.
• التوسّع — تشغيل المهام بالتوازي، ومصفوفة تجمع أنظمة تشغيل وإصدارات حزم مختلفة، والتنفيذ داخل حاوية.
• الختام — خطّ CI/CD متكامل، ثم كتابة GitHub Action خاصة من الصفر — وهي النقطة التي تنتقل فيها المنصّة من أداة تُستهلك إلى أداة يُبنى عليها.

النتيجة والدروس

اكتملت جميع بنود المسار ومُعلّمة في التوثيق ✅، وأصبح المستودع مرجعاً سريعاً يُعاد إليه عند إعداد خطّ أنابيب جديد.

1. الملاحظات التنفيذية تصمد. ملاحظة مرتبطة بملف يُشغّل تبقى صحيحة أو تنكسر بوضوح؛ والملاحظة النصية المجرّدة تتقادم بصمت.
2. ترتيب التعلّم ليس ترتيب التوثيق. إعادة ترتيب المواضيع حسب ما يُبنى عليه غيره أجدى من اتّباع فهرس المرجع الرسمي.
3. الترشيح يسبق التوسّع. معرفة paths وbranches مبكراً توفّر دقائق التنفيذ أكثر ممّا يوفره أي تحسين لاحق للمهام نفسها.

الروابط

• المستودع: github.com/i99dev/Github-Action-Tutorial