كيف تستخدم GitHub Actions لاستدعاء Webhooks والتحكم في مهامك عبر طلبات السحب (PRs)

في عالم تطوير البرمجيات المتسارع، أصبحت أدوات الأتمتة جزءًا لا يتجزأ من سير العمل اليومي. تُعد GitHub Actions ميزة ثورية أطلقتها منصة GitHub، وهي توفر إمكانيات هائلة لأتمتة المهام مباشرةً داخل مستودعاتك البرمجية. على الرغم من أنها قد تتطلب بعض التعود في البداية، إلا أنها أدوات قوية للغاية لعمليات التكامل المستمر (CI) والتحقق من جودة الكود على طلبات السحب (Pull Requests).

في هذا المقال، سنتعمق في كيفية استخدام GitHub Actions لاستدعاء Webhooks، وهي خطوة أساسية تفتح لك آفاقًا واسعة للتحكم في عملياتك عبر الإنترنت. فبمجرد أن تتمكن من استدعاء Webhook، يصبح الإنترنت بين يديك.

لماذا GitHub Actions لاستدعاء Webhooks بدلاً من الطرق التقليدية؟

قد تتساءل: “لقد كان GitHub يوفر Webhooks بالفعل، فلماذا نستخدم Actions؟” الإجابة بسيطة وواضحة: التحكم بالإصدار (Version Control).

التحكم بالإصدار والموثوقية

إذا كنت تعمل ضمن فريق على قاعدة بيانات برمجية مشتركة، فمن الضروري أن تكون قادرًا على تتبع كيفية حدوث التغييرات في الإعدادات ومن المسؤول عنها. مع إعدادات GitHub الأساسية، لا يمكنك معرفة هذه التفاصيل؛ يقوم شخص ما بإعداد وتكوين Webhook، وإذا فشل يومًا ما، فماذا بعد؟

باستخدام GitHub Actions، لا تحتاج إلى مغادرة محرر النصوص الخاص بك لمعرفة ما يحدث عند دفع (push) الكود الخاص بك. يتم تعريف Webhooks كجزء من الكود الخاص بك، مما يعني أنها تخضع لنظام التحكم بالإصدار. هذا يضمن:

• التتبع: يمكنك رؤية تاريخ التغييرات على Webhook ومن قام بها.
• المراجعة: يمكن مراجعة التغييرات على Webhooks من قبل الزملاء قبل دمجها.
• الاستعادة: يمكنك بسهولة العودة إلى إصدار سابق من إعداد Webhook إذا حدث خطأ ما.

بالإضافة إلى ذلك، توفر GitHub Actions عالمًا من الإمكانيات التي يمكنك تنفيذها، مثل تشغيل الاختبارات، وجمع تغطية الكود (code coverage)، والتحقق من جودة الكود (linting)، وغير ذلك الكثير. نظرًا لأن الكثير منا يستخدم GitHub يوميًا، فإن التعرف على هذه الأداة الجديدة أمر بالغ الأهمية.

خطوتك الأولى نحو الأتمتة: إنشاء GitHub Action

لنبدأ بإنشاء أول GitHub Action. أول ما تحتاج إليه هو إنشاء مجلد .github > workflows في جذر مستودعك. داخل هذا المجلد، سنضع ملفات Actions الخاصة بنا. لا يهم ما تسمي الملف؛ سيقوم GitHub بالتقاط جميع الـ Actions التي تضعها في هذا المجلد الخاص.

فيما يلي محتويات ملف Webhook الخاص بي كمثال. لدي نقطة نهاية API تسمى “Test Pedant” تتحقق من ملفات طلب السحب (PR) الخاص بي وتترك تعليقًا إذا لم أقم بكتابة أي اختبارات.

# This is a basic workflow that is manually triggered
name: Test reminder

# Controls when the action will run. Workflow runs when manually triggered using the UI or API.
on:
  # Trigger the workflow on push or pull request,
  # but only for the main branch
  pull_request:
    branches: [ main ]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  test_commentary:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Runs a single command using the runners shell
      - name: Webhook
        uses: distributhor/workflow-webhook@v1
        with:
          url: "http://amberisgreat.ngrok.io/api/test_pedant"
          json: '{
            "repository": "${{github.event.repository.full_name}}",
            "number": "${{github.event.number}}",
            "created_at": "${{github.event.pull_request.created_at}}",
            "updated_at": "${{github.event.pull_request.updated_at}}"
          }'

شرح تفصيلي لملف الـ Action

دعنا نستعرض هذا الملف سطرًا بسطر لفهم كيفية عمله:

• name: Test reminder: هذا هو اسم الـ Action الخاص بك. يظهر هذا الاسم في واجهة GitHub Actions لمساعدتك في التعرف على سير العمل (workflow).
• on:: يحدد هذا القسم متى سيتم تشغيل الـ Action. في هذا المثال، يتم تشغيله عند حدوث حدث pull_request (طلب سحب). يمكنك تحديد أحداث متعددة هنا.
• pull_request:: يحدد أن الـ Action سيتم تشغيله عند إنشاء أو تحديث طلب سحب.
• branches: [ main ]: يضمن هذا السطر أن الـ Action سيعمل فقط على طلبات السحب الموجهة إلى الفرع main. إذا أردت تشغيله لجميع طلبات السحب بغض النظر عن الفرع، يمكنك ببساطة استخدام on: [pull_request]. يوفر GitHub قائمة ضخمة من الأحداث التي يمكن أن تشغل Action.
• jobs:: هذا هو قائمة بالمهام التي سيتم تنفيذها كجزء من سير العمل. يمكن تشغيل المهام بالتسلسل أو بالتوازي.
• test_commentary:: هذا هو مفتاح لتعريف مهمتك (يمكن أن يكون أي اسم تختاره).
• runs-on: ubuntu-latest: يحدد هذا السطر نوع البيئة التي ستعمل عليها المهمة. في معظم الحالات، ستكون ubuntu-latest مناسبة، ولكن قد تتطلب بعض المهام بيئات محددة.
• steps:: تمثل الخطوات تسلسلًا من المهام التي سيتم تنفيذها كجزء من المهمة. يمكن أن تحتوي المهمة الواحدة على عدة خطوات.
• - name: Webhook: هذا هو اسم خطوتك (يمكن أن يكون أي شيء).
• uses: distributhor/workflow-webhook@v1: يشير هذا إلى الـ Action الذي سيتم استخدامه. في هذه الحالة، نحن نستخدم Action جاهزًا من مجتمع GitHub يسمى distributhor/workflow-webhook. يمكنك أيضًا كتابة Actions الخاصة بك!
• with:: تختلف الـ Actions المختلفة في المدخلات التي تتطلبها. يستخدم هذا الـ Action مفاتيح إدخال مثل url و json.
• url: "http://amberisgreat.ngrok.io/api/test_pedant": هذا هو نقطة النهاية (endpoint) التي تريد أن يستدعيها الـ Action الخاص بك.
• json: '...': يشير هذا إلى البيانات التي سترسلها إلى الـ Webhook. لاحظ استخدام متغيرات سياق GitHub Actions مثل ${{github.event.repository.full_name}} لسحب المعلومات ديناميكيًا من حدث GitHub.

فهم حمولة بيانات GitHub Actions (Payload)

كان العثور على معلومات حمولة البيانات (payload) لـ GitHub Action أمرًا صعبًا بعض الشيء في وثائق GitHub Actions. يتم تضمين حمولة البيانات لـ GitHub Action تحت الكائن github.event.

تحتاج أيضًا إلى معرفة الـ Action الذي تدفع البيانات منه، حيث تتوفر مفاتيح مختلفة على الكائن event اعتمادًا على الـ Action الذي تشير إليه (مدرجة كـ action في وثائق الحمولة). يمكنك العثور على الوثائق ذات الصلة هنا.

لاحظ أن مكتبتي لم تسمح لي بدفع الكائن event بأكمله إلى Webhook الخاص بي مباشرةً، ولهذا السبب ترى المفاتيح مستخرجة بشكل محدد في المثال. قد يقبل الـ Action الذي تكتبه الكائن event بأكمله (وفي هذه الحالة، نرجو أن تخبرنا بذلك!).

GitHub Actions قيد التنفيذ: المراقبة والتحقق

هذا كل ما تحتاجه لتبدأ! طالما أن Webhook الخاص بك يستجيب برمز حالة 200 OK، سيحصل الـ Action الخاص بك على علامة خضراء تشير إلى النجاح.

إذا فشل الـ Action الخاص بك، يمكنك التحقق مما حدث خطأ في علامة التبويب Actions ضمن مستودعك. في حالتي، يفشل لأن نفق ngrok الخاص بي لم يعد قيد التشغيل.

مكافأة: استخدام ngrok للاختبار المحلي الآمن

على الرغم من أنه غير مرتبط مباشرةً بميزة GitHub Actions، إلا أنه من المفيد جدًا أن تكون قادرًا على فتح منفذ مستضاف محليًا (locally-hosted port) للخدمات الخارجية. في هذه الحالة، أريد أن يقوم GitHub Action الخاص بي بتشغيل خادمي المحلي (localhost) حتى أتمكن من اختبار حمولة البيانات وتنفيذ Webhook الخاص بي. عندما أقوم بنشر هذا في بيئة الإنتاج، سأستبدل الـ url بالنسخة الإنتاجية من الكود.

هنا يأتي دور ngrok! ngrok هي خدمة مجانية تنشئ نفقًا آمنًا إلى خادمك المحلي. يمكن لشركتي دفع مقابل عناوين URL محجوزة (لأغراض تطوير الويب إلى الجوال)، ولكن لأغراضك هنا، النسخة المجانية رائعة.

ما عليك سوى تثبيته باستخدام brew install ngrok (أو أي مدير حزم تستخدمه)، ثم قم بتشغيل خادمك المحلي الذي يقدم كود Webhook، ثم نفذ الأمر ngrok http <your-port>. لقد أنشأت الآن اتصالًا عامًا بخادمك المحلي. سيتمكن GitHub من الوصول إليه ويمكنك اختبار التنفيذ الخاص بك. فقط كن على دراية بأن الأنفاق المجانية تنتهي صلاحيتها بعد فترة وتتطلب عنوان URL جديدًا.

آفاق المستقبل: سوق GitHub Actions

إذا ألهمك هذا المقال ببعض الأفكار الرائعة لما يمكنك فعله بالتغييرات في مستودعاتك على GitHub، فعليك استكشاف سوق Actions Marketplace. ستجد فيه أن بعض المطورين الموهوبين قد ابتكروا جميع أنواع الـ Actions التي يمكن تشغيلها عند حدوث أحداث معينة في GitHub الخاص بك. ستجد هنا أدوات التدقيق التلقائي (auto-linters)، واتصالات Jira، وأدوات النشر (deployment tools)، وغير ذلك الكثير. نتمنى لك أتمتة ممتعة!

الخلاصة التقنية

تُعد GitHub Actions نقلة نوعية في أتمتة سير عمل التطوير، خاصةً عند دمجها مع Webhooks. إن القدرة على تعريف وتتبع إعدادات Webhook كجزء من قاعدة الكود نفسها، تحت مظلة التحكم بالإصدار، تعالج تحديات كبيرة تتعلق بالشفافية والموثوقية التي كانت تواجهها الطرق التقليدية. تتيح هذه المرونة للمطورين ليس فقط أتمتة التفاعلات مع الأنظمة الخارجية، بل أيضًا بناء أنظمة CI/CD قوية ومراجعة جميع التغييرات بشكل منهجي. استخدام أدوات مثل ngrok يكمل هذه المنظومة بتوفير بيئة اختبار محلية آمنة وفعالة، مما يجعل GitHub Actions أداة لا غنى عنها لأي فريق تطوير يسعى لتحقيق أقصى درجات الكفاءة والتحكم.