Jenkins والتكامل المستمر المؤسسي

المشغلات والـ Webhooks والـ Multibranch

18 دقيقة الدرس 8 من 28

المشغلات والـ Webhooks والـ Multibranch

أسلوب الـ Polling هو نهج المبتدئين في عالم CI: يستيقظ Jenkins كل بضع دقائق ليسأل نظام إدارة الكود "هل هناك أي جديد؟"، ويهدر موارد المعالج في ذلك سواء لمس المطورون الكود أم لم يلمسوه. في بيئة تضم مئات الـ Pipelines، يعني ذلك آلاف طلبات API المهدورة في الساعة. الحل في بيئات الإنتاج هو التشغيل المبني على الأحداث — يرسل نظام إدارة الكود webhook فور وصول أي commit أو Pull Request، ويستجيب Jenkins في أقل من ثانية. ادمج ذلك مع Multibranch Pipelines وستحصل على نموذج CI الكامل المعتمد في الشركات الكبرى: كل فرع وكل PR يُكتشف تلقائيًا ويُبنى ويُبلَّغ عنه دون أن يضطر أحد لتهيئة job جديدة يدويًا.

كيف تعمل Webhooks الخاصة بنظام SCM

الـ webhook هو طلب HTTPS من نوع POST يرسله نظام SCM (GitHub أو GitLab أو Bitbucket) إلى رابط تسجله مسبقًا. يكشف Jenkins هذا الرابط على المسارات /github-webhook/ أو /gitlab/notify_commit أو المسار العام /generic-webhook-trigger/invoke حسب البلاجين المثبَّت. تسير العملية كالتالي:

يدفع المطور commit جديدًا أو يفتح PR.
يوقّع SCM الحمولة بتوقيع HMAC-SHA256 سري ويرسل POST إلى Jenkins.
يتحقق Jenkins من التوقيع ويحدد أي job(s) تتطابق مع رابط المستودع.
تُوضع الـ Pipeline المطابقة في قائمة الانتظار فورًا — ويكون الكمون الإجمالي أقل من ثانيتين عادةً.

CI المبني على الـ Webhook: يُشغِّل حدث الدفع Jenkins في أقل من ثانيتين؛ ثم يُرسَل الناتج إلى SCM كـ commit status check.

تسجيل Webhook في GitHub

داخل مستودعك على GitHub: Settings → Webhooks → Add webhook. اضبط Payload URL على https://<jenkins-server>/github-webhook/، واختر Content type بقيمة application/json، والصق السر الذي ولّدته. اختر Just the push event أو حدد الأحداث يدويًا (push + pull_request يكفيان لمعظم الحالات). يتحقق Jenkins من كل طلب وارد بمقارنته بذلك السر؛ يُسقط الطلبات التي يغيب عنها التوقيع أو يكون خاطئًا بصمت.

قواعد جدار الحماية للطلبات الواردة. يجب أن يكون Jenkins قابلًا للوصول من نطاقات IP الخاصة بـ GitHub (api.github.com/meta يسردها تحت مفتاح hooks). في البيئات المؤسسية الخاصة، مرِّر الطلبات عبر reverse proxy (nginx أو AWS ALB) مع قائمة السماح بدلًا من كشف Jenkins مباشرة على الإنترنت.

في Declarative Pipeline، صرِّح بالمشغل ليبقى موثقًا في الكود:

pipeline {
  agent any

  triggers {
    githubPush()                    // يُشغَّل عند كل push عبر webhook
    // لـ GitLab:  gitlab(triggerOnPush: true, triggerOnMergeRequest: true)
  }

  stages {
    stage('Build') {
      steps {
        sh 'make build'
      }
    }
  }
}

بعد حفظ هذا الـ Jenkinsfile، انقر Build Now مرة واحدة لتسجيل المشغل. بعد ذلك تبدأ الـ Pipeline تلقائيًا عند كل push.

بناء PRs وفحوصات Commit Status

بناء الـ PR هو شبكة الأمان التي تجعل التطوير المبني على trunk عمليًا على نطاق واسع. عندما يفتح مطور PR، يُطلق SCM webhook من نوع pull_request. يسحب Jenkins الـ merge commit (ما سيبدو عليه الفرع بعد الدمج مع الأساس)، يشغّل الـ Pipeline الكاملة، ثم يستدعي commit-status API الخاص بـ SCM ليرسل required status check. لن يسمح GitHub بالضغط على زر Merge حتى يتحول هذا الفحص إلى اللون الأخضر.

يتولى بلاجن GitHub Branch Source هذا تلقائيًا عند استخدامك Multibranch Pipeline — لا حاجة لتهيئة إرسال commit-status يدويًا.

Multibranch Pipelines

الـ Multibranch Pipeline هي مجلد من الـ jobs يُنشئها Jenkins ويحذفها تلقائيًا كلما ظهرت فروع أو اختفت في مستودعك. كل فرع يحتوي على Jenkinsfile يحصل على سجل بناء خاص به، ونطاق بيانات اعتماد خاص به، ومجموعة متغيرات بيئية خاصة به (BRANCH_NAME، CHANGE_ID، CHANGE_TARGET). هذا هو الوحدة الصحيحة لـ CI على نطاق واسع — لا job واحدة لكل فرع تُهيَّأ يدويًا.

أنشئ واحدة عبر New Item → Multibranch Pipeline. الأقسام الرئيسية هي:

Branch Sources — أضف مصدر GitHub/GitLab، أدخل رابط المستودع، واختر بيانات الاعتماد (PAT محدود الصلاحيات بـ contents:read وstatuses:write كافٍ).
Behaviors — اكتشاف الفروع، اكتشاف PRs من forks (دمج مع الهدف)، حذف الفروع القديمة.
Build Configuration — عبر Jenkinsfile في المسار Jenkinsfile (أو مسار مخصص للـ monorepos).
Scan Triggers — اضبطه على يوم واحد كخيار احتياطي؛ الـ webhook هو المشغل الفعلي.

# مقتطف Jenkinsfile — مراحل مشروطة بالفرع
pipeline {
  agent any

  stages {
    stage('Test') {
      steps { sh './gradlew test' }
    }

    stage('Deploy to Staging') {
      when { branch 'main' }         // فقط على الفرع الرئيسي
      steps { sh './deploy.sh staging' }
    }

    stage('Deploy to Production') {
      when { branch 'release/*' }    // فقط على فروع release/*
      steps { sh './deploy.sh production' }
    }

    stage('PR Smoke Tests') {
      when { changeRequest() }       // فقط في بناءات PR
      steps { sh './smoke-tests.sh' }
    }
  }
}

استخدم changeRequest() للتحكم في الاختبارات المكلفة. تختبارات الوحدة تعمل عند كل push؛ أما اختبارات التكامل ومسح الحاويات فهي مكلفة — قيّدها بـ when { not { changeRequest() } } لتعمل فقط على الكود المدمج، مما يُبقي ردود فعل PR سريعة.

Organization Folders (بلاجن GitHub Organization)

إذا كانت شركتك تمتلك عشرات المستودعات، أنشئ مجلد GitHub Organization واحدًا بدلًا من Multibranch Pipeline لكل مستودع. سيمسح Jenkins كل مستودع في المؤسسة، ويجد التي تحتوي على Jenkinsfile، وينشئ Multibranch Pipeline لكل منها تلقائيًا. تُلتقط المستودعات الجديدة في أول مسح تالٍ (أو عبر webhook). هكذا تدير المؤسسات الهندسية الكبيرة مئات الـ Pipelines بحد أدنى من العبء الإداري.

أنماط الفشل في بيئة الإنتاج

فشل تسليم الـ Webhook بصمت. يُعيد GitHub محاولة إرسال الـ webhooks الفاشلة ثلاث مرات بنهج exponential back-off ثم يتوقف. تحقق دائمًا من Settings → Webhooks → Recent Deliveries عندما لا يُشغَّل build بعد push. السبب الأكثر شيوعًا هو وجود Jenkins خلف جدار حماية لم يُدرج نطاقات IP الخاصة بـ GitHub.

عواصف مسح الفروع. عند إضافة مصدر GitHub Organization يضم 200 مستودع لأول مرة، يُطلق Jenkins 200 عملية مسح متزامنة. قيِّد التزامن ببلاجن Throttle Concurrent Builds أو اضبط فترة المسح لـ orphanedItemStrategy على كل ساعة واعتمد على الـ webhooks للتشغيل الفوري.

لا تخزن سر الـ webhook أبدًا داخل الـ Jenkinsfile. احتفظ به في بيانات اعتماد Jenkins (نوع Secret Text)، وأشر إليه في إعدادات GitHub Branch Source، وقم بتدويره عبر سير عمل إدارة الأسرار لديك. السر المُسرَّب يتيح للمهاجم تشغيل عمليات pipeline عشوائية.

بدمج SCM webhooks مع Multibranch Pipelines وفحوصات commit-status تحصل على دورة ردود فعل CI الكاملة في الإنتاج: كل commit على كل فرع يُتحقق منه في ثوانٍ، يرى أصحاب PRs النجاح أو الفشل قبل أن يراجع أحد الكود، والفرع الرئيسي محمي دائمًا بالفحوصات الإلزامية. هذا هو المعيار الذي تعمل وفقه كل شركة تقنية كبرى.