الفصل السابع: Events (Triggers) في GitHub Actions

وصلنا الآن إلى قلب GitHub Actions الحقيقي.

إذا كانت الـ Workflow هي الخطة، فإن الـ Event هي الزر الذي يشغل الخطة.

بدون Event لن يتم تشغيل أي Workflow أبداً.

---

ما هو Event أو Trigger؟

ببساطة:

حدث يقع داخل GitHub
↓
يؤدي إلى تشغيل Workflow

مثال:

Push
↓
تشغيل Workflow

أو:

Pull Request
↓
تشغيل Workflow

أو:

Release
↓
تشغيل Workflow

---

تشبيه من الواقع

تخيل لديك مصباح ذكي.

المصباح = Workflow

زر التشغيل = Event

بدون ضغط الزر لن يحدث شيء.

---

أين يتم تعريف Event؟

دائماً داخل:

on:

هذه الكلمة من أهم الكلمات في GitHub Actions.

---

مثال:

on:
  push:

---

GitHub يفهمها:

عندما يحدث Push
شغل Workflow

---

كيف يعمل GitHub داخلياً؟

عندما ترفع الكود:

git push origin main

GitHub يراقب Repository.

---

فور وصول Push:

Repository
    ↓
Push Event
    ↓
GitHub Actions
    ↓
Workflow

---

أول Event: Push

الأكثر استخداماً في العالم.

---

ما هو Push؟

عندما ترسل Commit إلى GitHub.

مثال:

git add .
git commit -m "update"
git push origin main

---

هنا يحدث Event:

Push

---

أبسط مثال

on:
  push:

---

معناه:

أي Push
على أي Branch
يشغل Workflow

---

ماذا يحدث عملياً؟

أنت ترفع:

Route::get('/users');

---

ثم:

git push

---

GitHub يشغل:

Workflow
 ↓
Tests
 ↓
Build
 ↓
Deploy

---

متى يستخدم Push؟

في CI غالباً.

---

مثال Laravel:

Push
 ↓
Composer Install
 ↓
PHPUnit
 ↓
PHPStan

---

هذه أكثر حالة استخدام شيوعاً.

---

تقييد Push على Branch معين

مثلاً:

لا أريد التشغيل إلا على:

main

---

نكتب:

on:
  push:
    branches:
      - main

---

المعنى:

Push على main
✓ شغل

Push على develop
✗ لا تشغل

---

عدة Branches

on:
  push:
    branches:
      - main
      - develop

---

المعنى:

main
✓

develop
✓

feature-x
✗

---

استثناء Branch

on:
  push:
    branches-ignore:
      - develop

---

المعنى:

أي Branch
إلا develop

---

ثاني Event: Pull Request

هذا من أهم Events في الشركات.

---

ما هو Pull Request؟

عندما يريد مطور دمج كوده.

---

مثال:

feature-login
 ↓
main

---

ينشئ:

Pull Request

---

قبل الدمج.

---

لماذا هو مهم؟

لأننا نريد فحص الكود قبل دخوله إلى Main.

---

مثال:

on:
  pull_request:

---

المعنى:

عند إنشاء PR
شغل Workflow

---

ماذا يحدث؟

Developer
 ↓
Pull Request
 ↓
GitHub Actions
 ↓
Tests
 ↓
Review
 ↓
Merge

---

مثال عملي

on:
  pull_request:

jobs:
  test:

---

عند فتح Pull Request:

Run Tests

---

إذا نجحت:

✅ يمكن الدمج

---

إذا فشلت:

❌ يمنع الدمج

---

تقييد Pull Request

مثلاً:

on:
  pull_request:
    branches:
      - main

---

المعنى:

أي PR يستهدف main
شغل Workflow

---

ثالث Event: Schedule

من أقوى Events.

---

ما هو Schedule؟

تشغيل Workflow في وقت محدد.

مثل Cron Job.

---

مثال:

كل يوم
كل ساعة
كل أسبوع

---

الصيغة

on:
  schedule:

---

لكن تحتاج Cron Expression.

---

مثال:

on:
  schedule:
    - cron: '0 0 * * *'

---

المعنى:

كل يوم
الساعة 00:00

---

كيف يقرأها GitHub؟

Minute Hour Day Month Weekday

---

مثال:

cron: '0 * * * *'

---

المعنى:

كل ساعة

---

مثال:

cron: '*/15 * * * *'

---

المعنى:

كل 15 دقيقة

---

استخدامات Schedule

---

نسخ احتياطي

Every Day
 ↓
Database Backup

---

تنظيف ملفات

Every Night
 ↓
Delete Temp Files

---

فحص SSL

Every Day
 ↓
Check Expiration

---

تحديث Dependencies

Weekly
 ↓
Check Updates

---

رابع Event: Workflow Dispatch

من أكثر Events التي ستستخدمها في DevOps.

---

ما هو Workflow Dispatch؟

تشغيل Workflow يدوياً.

---

بدلاً من:

Push

أنت تضغط زر تشغيل.

---

الصيغة:

on:
  workflow_dispatch:

---

---

بعد رفع Workflow:

اذهب إلى:

Actions

---

ستجد:

Run Workflow

---

اضغط عليه.

---

GitHub يشغل Workflow فوراً.

---

لماذا نستخدمه؟

---

Deploy يدوي

مثلاً:

Deploy Production

---

لا تريد النشر عند كل Push.

---

تريد:

زر Deploy

---

Workflow Dispatch مثالي لذلك.

---

مثال

on:
  workflow_dispatch:

---

المعنى:

لا تشغل تلقائياً

شغل فقط عند الضغط على Run Workflow

---

Workflow Dispatch مع Inputs

احترافي جداً.

---

مثال:

on:
  workflow_dispatch:
    inputs:
      environment:

---

عند الضغط:

Environment:
Production
Staging
Development

---

المستخدم يختار.

---

ثم يبدأ التنفيذ.

---

خامس Event: Release

---

ما هو Release؟

عندما تنشئ إصداراً جديداً.

مثلاً:

v1.0.0

---

داخل GitHub.

---

ثم:

Create Release

---

يحدث Event.

---

الصيغة:

on:
  release:

---

المعنى:

عند إنشاء Release
شغل Workflow

---

مثال

Release v2.0
 ↓
Build Docker Image
 ↓
Deploy

---

شائع جداً في الشركات.

---

سادس Event: Tag

---

ما هو Tag؟

علامة على Commit.

---

مثال:

git tag v1.0.0
git push origin v1.0.0

---

GitHub يرى:

Tag Created

---

تشغيل Workflow عند إنشاء Tag

on:
  push:
    tags:
      - 'v*'

---

المعنى:

v1.0.0
✓

v2.0.0
✓

test
✗

---

لماذا نستخدم Tags؟

---

إصدار Docker

Tag v1.0
 ↓
Docker Build
 ↓
Docker Push

---

إصدار تطبيق

Tag v2.5
 ↓
Release Build

---

Branch Filtering

هذه ليست Event مستقلة.

لكنها فلتر مهم.

---

مثال:

on:
  push:
    branches:
      - main

---

المعنى:

Push
+
Branch Main
=
Run Workflow

---

عدة Branches

on:
  push:
    branches:
      - main
      - develop
      - staging

---

GitHub يقرأها:

main
OR
develop
OR
staging

---

Multiple Events

الآن نصل للجزء الاحترافي.

---

يمكن لـ Workflow واحدة الاستماع لأكثر من Event.

---

مثال:

on:
  push:
  pull_request:

---

المعنى:

Push
OR
Pull Request

---

أي حدث منهما سيشغل Workflow.

---

مثال عملي

on:
  push:
    branches:
      - main

  pull_request:
    branches:
      - main

---

المعنى:

Push على Main
✓

PR إلى Main
✓

---

مثال احترافي

on:
  push:
    branches:
      - main

  workflow_dispatch:

  schedule:
    - cron: '0 0 * * *'

---

هذه Workflow تعمل في ثلاث حالات:

Push
OR
Manual Run
OR
Daily Schedule

---

كيف يفكر GitHub في Events؟

تخيل هذا المخطط:

Repository
     │
     │
     ├── Push
     │      │
     │      ▼
     │   Workflow
     │
     ├── Pull Request
     │      │
     │      ▼
     │   Workflow
     │
     ├── Release
     │      │
     │      ▼
     │   Workflow
     │
     ├── Schedule
     │      │
     │      ▼
     │   Workflow
     │
     └── Manual Run
            │
            ▼
         Workflow

---

ماذا تستخدم فعلياً في مشاريع Laravel + Docker + Coolify؟

في أغلب الشركات ستستخدم:

CI

on:
  pull_request:

لتشغيل الاختبارات.

---

Build

on:
  push:
    branches:
      - main

لبناء الصورة.

---

Deploy Production

on:
  workflow_dispatch:

أو:

on:
  push:
    branches:
      - main

---

Backups

on:
  schedule:

---

إذا فهمت Events جيداً فأنت أصبحت قادراً على التحكم متى تبدأ أي Pipeline في GitHub Actions، وهي خطوة أساسية قبل الانتقال إلى الفصل التالي: Jobs بالتفصيل (Dependencies – Parallel Jobs – Sequential Jobs – Needs – Strategy)، وهو المكان الذي تبدأ فيه بناء Pipelines احترافية حقيقية.