إنشاء روبوت Slack بكمال لاستدعاء GitHub Actions عبر Hubot

إذا كنت تستخدم GitHub Actions كأداة لبناء ونشر البرمجيات ويستخدم فريقك أيضًا تطبيق Slack، هل تعلم أنه يمكنك القيام بذلك دون الحاجة لمغادرة Slack؟ أنشئ بوت في Slack لاستدعاء سير العمل من GitHub Actions مباشرةً من Slack بشكل تلقائي!

في هذا البرنامج التعليمي، ستتعلم كيفية إعداد بوت دردشة جديد في Slack باستخدام أداة بناء البوت المسماة Hubot وتشغيل سير العمل في GitHub Actions تلقائيًا لنشر الشفرة على خادم.

لنبدأ!

المتطلبات المسبقة

هذا البرنامج التعليمي سيكون عرضًا توضيحيًا عمليًا. إذا كنت ترغب في متابعة الدرس، تأكد من أنك تمتلك ما يلي:

• A Slack Workspace
• A GitHub account and a GitHub personal token
• A Linux server to deploy code to – This tutorial will use Ubuntu 19.
• A local Linux machine – This tutorial will use Ubuntu so that all local commands will be Linux. If you’re running another operating system, the commands may be slightly different.
• بيانات تسجيل الدخول SSH للاتصال بالخادم الذي ستنشر عليه الشفرة.
• A code editor of your choice that understands YAML like Visual Studio Code.

مقالات ذات صلة:تلقيم الإجراءات Git على الجانب العميل باستخدام Git Hooks

إنشاء مشروع وسير عمل في GitHub Actions

قبل أن تتمكن من استدعاء سير عمل GitHub Actions بسرعة من Slack، يجب عليك أولاً إنشاء السير العمل.

لإنشاء السير العمل، دعنا ننشئ مجلد مشروع لاحتواء جميع الملفات التي ستعمل عليها.

ذات صلة:كيفية تشغيل إعداد GitHub لـ Visual Studio Code!

1. افتح تطبيق الطرفية المفضل لديك.

2. الآن قم بتشغيل سلسلة الأوامر أدناه لإنشاء مجلد المشروع المسمى Hubot والانتقال إليه.

mkdir ~/Hubot # إنشاء دليل بأسم Hubot
cd ~/Hubot    # تغيير الدليل إلى Hubot

3. بعد ذلك، قم بتشغيل npm init لإنشاء ملف package.json لـ Node.JS. تشغيل npm init ينشئ مشروع Node.JS قياسي يتضمن ملف package.json الذي يحتوي على معلومات مختلفة حول المشروع وأي حزم NPM تعتمد عليها.

npm init      # يبدأ ملف package.json

4. الآن، قم بإنشاء دليل workflows وملف عملية العمل deploy.yml. ملف عملية العمل هو سلسلة من الخطوات المحددة في تسلسل سير عمل GitHub Actions ستتبعه.

mkdir .github/workflows && touch deploy.yml

5. بعد ذلك، قم بتعريف كل واحد من أسرار GitHub سيقرأها سير عملك. سيشير السير الذي تقوم بإنشائه إلى هذه الأسرار. نظرًا لأنك ستحتاج إلى عنوان الخادم الخاص بك واسم المستخدم وكلمة المرور ومنفذ الخادم الخاص بك للاتصال عبر SSH ، دعنا ننشئ أسرار GitHub.

قم بزيارة عنوان الويب هذا https://github.com/yourusername/yourrepository/settings/secrets/actions حيث ستضيف أسرار GitHub الخاصة بك. قم بتبديل yourusername باسم مستخدم GitHub الخاص بك و yourrepository بمستودع GitHub الخاص بك.

انقر على زر إضافة سر جديد للمستودع ، كما هو موضح أدناه ، لملء معلومات حول السر الذي تضيفه.

6. الآن قم بملء حقول اسم وقيمة السر ، ثم انقر على إضافة سر لحفظه. سيتم توجيه الصفحة إلى صفحة أسرار GitHub حيث سترى جميع أسرارك. لإضافة المزيد من الأسرار ، انقر على زر السر الجديد في المستودع كما فعلت سابقًا.

تأكد من حفظ الأسرار للمتغيرات المعطاة بنفس الاسم الذي ستشير فيه إلى نفس المتغيرات ، وهي HOST و USERNAME و PASSWORD و PORT.

7. في النهاية ، افتح ملف سير العمل ~/Hubot/.github/workflows/deploy.yml في محرر الأكواد الخاص بك ، وانسخ/الصق الكود التالي. الكود أدناه هو سير العمل الذي سيتم تشغيله كلما قمت بتشغيل السير العمل عبر سلاك لاحقًا.

عندما تقوم بإستدعاء السير العمل ، ستحدث عدة إجراءات:

• ستقوم GitHub Actions بتحليل ملف سير العمل أدناه للاتصال بـ SSH إلى الهدف host المحدد في السر الخاص بـ HOST باستخدام الاسم وكلمة المرور المحددة كأسرار مستوردة للمشروع.
• ثم سيقوم سير العمل بتنزيل محتويات مستودع GitHub لفرع محدد ($branchName) من خلال تشغيل git pull origin$branchName. تأكد من أن اسم الفرع يحتوي على الشيفرة التي ترغب في نشرها.
• سوف تقوم باستخدام حزمة السير العمل من سوق جيتهاب تسمى ssh-remote-commands. تحتوي هذه الحزمة على طرف جيد للتغلب على الحاجة إلى توفير مضيف واسم مستخدم وكلمة مرور ومنفذ وأمر لتشغيله على الإنتاج.

تأكد من أن خادمك قد قام بتثبيت Git بشكل صحيح مع بيانات الاعتماد اللازمة لاسترجاع الشيفرة من مستودع GitHub

# الاسم الذي سيتم الرجوع إليه يتم التعامل معه بشكل برمجي بشكل كبير
name: deploy 
on:
  # يعني مستودع الحدث repository_dispatch على كل تنبيه API، 
  # يتم تنفيذ هذا الملف بأكمله
  repository_dispatch: 
    types: [deploy-service]
# يمكن أن يكون هناك وظائف متعددة، ولكن في الوقت الحالي، 
# ستعمل هذه الدورة التعليمية على واحدة فقط
jobs:
  deploy:
    name: Deploy
    # اسم الصورة الرئيسية حيث يتم تنفيذ جميع الشيفرات في YAML
    runs-on: ubuntu-latest
    steps:
    - name: executing remote ssh commands using password
      # appleboy/ssh-action@master إنها حزمة مفتوحة المصدر 
      # التي تسجل الدخول إلى خادم عبر ssh وتنفذ السيناريو
      uses: appleboy/ssh-action@master
      # هذه هي عادة المتغيرات التي تحتاجها الحزمة 
      # لتسجيل الدخول إلى الخادم وتنفيذ السيناريو
      with:
       # الأسرار هي المتغيرات من 
       # https://docs.github.com/en/actions/security-guides/encrypted-secrets

       # مضيف الخادم الخاص بك المخزن في أسرار github بنفس الاسم HOST
        host: ${{ secrets.HOST }} 
        # اسم مستخدم خادمك لتسجيل الدخول 
        # المخزن في أسرار github بالاسم USERNAME
        username: ${{ secrets.USERNAME }} 
        # كلمة مرور خادمك لتسجيل الدخول 
        # المخزنة في أسرار github بالاسم PASSWORD
        password: ${{ secrets.PASSWORD }} 
        # منفذ خادمك لتسجيل الدخول 
        # المخزن في أسرار github بالاسم PORT
        port: ${{ secrets.PORT }}  
        # يمكن أن يكون deploy-app.sh أي شيء، على سبيل المثال يمكنك سحب الشيفرة من GitHub
        # وإعادة تشغيل خادم الويب الخاص بك أو الطوابير أي شيء
        # تأكد من أنك قد قمت بتكوين المستودع على خادمك
        # يمكنك تشغيل العديد من السيناريوهات كما تشاء
        script: git pull origin {{ github.event.client_payload.branch 

تنفيذ سير العمل يدويًا

لقد قمت الآن بإنشاء سير عمل GitHub Actions لاستدعاءه عبر Slack. ولكن في هذه النقطة ، يكون الكود على جهازك المحلي فقط. لتشغيل سير العمل ، ستحتاج إلى دفع الكود إلى GitHub.

تشغيل سلسلة الأوامر أدناه يخبر git أين يجب دفع الكود وسحبه منه ، في هذا المثال ، من مستودع GitHub البعيد الخاص بك. في الأمر git remote add origin أدناه ، استبدل yourusername و yourrepository باسم مستخدم GitHub ومستودعك

# قم بفتح github.com وإنشاء مستودع
git init # يبدأ git
git remote add origin https://github.com/yourusername/yourrepository.git
git add . # يضيف الملفات المنشأة حديثًا لتتبع git
git commit -m "Created GitHub workflow file"
git push -u origin master

دعنا نختبر أولاً ما إذا كان الكود الخاص بك يعمل. استدعي الكود يدويًا باستخدام أداة curl الشهيرة.

قم بتشغيل الأمر أدناه لإجراء طلب POST إلى عنوان URL المستودع الخاص بك على GitHub https://github.com/username/repository/dispatches لإعلام GitHub بتشغيل ملف سير العمل deploy.yml الذي قمت بإنشائه سابقًا. استبدل username باسم مستخدمك الفعلي على GitHub و repository بمستودع GitHub الخاص بك.

استبدل $github_personal_token في الكود أدناه بالرمز الشخصي الخاص بك.

# يقوم بطلب نشر على عنوان url https://github.com/username/repository/dispatches
curl-X POST  https://github.com/username/repository/dispatches \
# يضيف رأس لقبول نوع المحتوى
-H 'Accept: application/vnd.github.everest-preview+json' \
# يضيف رأس للتفويض
-H "Authorization: token $github_personal_token" \
# يضيف محتوى json في جسم الطلب النشري بحيث يمكنك إرسال معلمات متعددة
# من هذا القسم من البيانات ويمكنك أداء إجراءات مختلفة استنادًا إلى الوسيطات
--data '{"event_type": "deploy-service", "client_payload": {"environment": "'"$1"'", "ref": "'"$2"'"}}' # يمكنك تمرير اسم البيئة والإشارة كاسم فرعي بحيث تعرف أي فرع تنتقل إليه على أي خادم

إنشاء Slack Bot مع Hubot

نظرًا لأنه كنت قادرًا على تشغيل سير العمل في GitHub يدويًا، فهذا بداية جيدة. الآن دعونا نحاول أتمتة نفس الخطوات اليدوية عبر Slack Bot. ستقوم بإنشاء Slack Bot، الذي يستمع إلى أوامرك ويشغل سير العمل في GitHub مع الوسيطات.

لديك خياران لإنشاء Slack Bot، إما من البداية أو من حزمة hubot المبنية مسبقًا لمساحات العمل في slack. في هذا البرنامج التعليمي، ستستخدم حزمة Bot المبنية مسبقًا تسمى Hubot. Hubot هي أداة تلقائية مفتوحة المصدر تتكامل مع خدمات الدردشة مثل Slack، Discord، Gitter، TeamSpeak، إلخ.

إنشاء روبوت مخصص دون استخدام تطبيق مثل Hubot يستغرق وقتًا طويلاً. لماذا؟ لأنك ستتعامل مع جميع عمليات الإعداد، الاستماع إلى الويب هوك، واستضافة الروبوت. لذا في هذا البرنامج التعليمي، ستستخدم تطبيق Hubot Slack لتبسيط جميع تلك العمليات.

تثبيت Hubot باستخدام Npm

نظرًا لأنك تستخدم Hubot لإنشاء روبوت Slack، دعنا نقوم أولاً بتنزيل وتثبيت Hubot على جهازك المحلي. Hubot سيكون الرابط الذي يربط بين Slack وأفعال GitHub.

1. في الطرفية الخاصة بك، انتقل (cd) إلى دليل مشروعك (~/Hubot).

cd ~/Hubot

2. قم بتثبيت حزمة yo و generator-hubot بشكل عام (-g) على جهازك المحلي باستخدام أمر npm install أدناه. تساعدك حزمة yo في تثبيت مشاريع جديدة من خلال إنشاء مشاريع بأي لغة (ويب، جافا، بيثون، سي شارب، إلخ). حزمة generator-hubot تستخدم حزمة yo لتثبيت جميع التبعيات مع إعدادات البداية.

بمجرد التثبيت، يمكنك تشغيل أمر yo من أي مكان حيث تم تثبيته بشكل عام.

npm install -g yo generator-hubot

3. الآن، قم بإنشاء قالب أساسي لـ Hubot boilerplate باستخدام الأمر التالي. القالب هو جزء من الشفرة المضمن في العديد من الأماكن. بدون قالب، ستحتاج دائمًا إلى كتابة الشفرة من البداية.

الأمر أدناه ينشئ قالبًا أساسيًا لـ Hubot في دليل مشروعك. يربط القالب Hubot بـ Slack (--adapter=slack) بحيث يمكن للروبوت الاستماع والرد على الرسائل داخل قناة الـ Slack. yo hubot --adapter=slack

yo hubot --adapter=slack

إضافة Hubot إلى مساحة عمل Slack الخاصة بك

الآن بعد تثبيت Hubot على جهازك المحلي، تحتاج إلى تكوين Hubot للتواصل مع Slack.

لنقم بتثبيت Hubot في مساحة عمل Slack الخاصة بك.

1. قم بفتح متصفح الويب الخاص بك وانتقل إلى إعدادات مسؤول Slack الخاصة بك باستخدام عنوان URL، مثل https://workspacename.slack.com/admin/settings. استبدل workspacename بالاسم الفعلي لمساحة العمل الخاصة بـ Slack الخاصة بك.

انقر على تكوين التطبيقات oفي اللوحة اليسرى، كما هو موضح أدناه، بحيث يمكنك البحث عن Hubot في السوق. يحتوي Slack على سوق حيث يمكنك العثور على تطبيقات مبنية مسبقًا.

2. انقر على شريط البحث، ثم اكتب hubot للبحث عن Hubot في السوق وحدد Hubot.

الآن، انقر على زر إضافة إلى Slack كما تراه أدناه، لإضافة Hubot إلى مساحة عمل Slack الخاصة بك.

3. أخيرًا ، قم بملء بعض المعلومات العامة حول الروبوت الخاص بك ، مثل الاسم (deployerhubot) والرمز. احرص على الحفاظ على رمز الواجهة حيث ستستخدمه لاحقًا في مشروع Hubot Deployer لتفعيل الروبوت من مشروع Hubot الذي قمت بإنشائه سابقًا.

اختبار تكامل سير عمل GitHub Actions مع Slack

لقد قمت الآن بتثبيت Hubot على مساحة عمل Slack الخاصة بك ، لذا دعنا نقوم بفحص الروبوت عن طريق الاستماع وإرسال الرسائل إلى القناة. ولكن أولاً ، يجب عليك تنشيط الروبوت.

1. قم بتشغيل الأمر أدناه داخل دليل المشروع الرئيسي لتنشيط الروبوت لـ Slack (--adapter slack) من مستودع Hubot الخاص بك (./bin/hubot). تأكد من استبدال $token برمز الواجهة البرمجية الذي قمت بالتوجيه إليه سابقًا

HUBOT_SLACK_TOKEN=$token ./bin/hubot --adapter slack

2. قم بتشغيل الأمر أدناه لدعوة (/invite) الروبوت (botusername) إلى قناتك على Slack. استبدل botusername باسم الروبوت الذي قمت بتسجيله في الخطوة الثالثة من قسم “إضافة Hubot إلى مساحة عمل Slack الخاصة بك”.

/invite deployerhubot

الآن ، قم بذكر روبوت برسالة نصية في Slack ، مثل @deployerhubot ping, لاختبار ما إذا كان التكامل يعمل. إذا رد الروبوت PONG ، كما هو موضح أدناه ، فإنك جاهز.

إذا لم يرد الروبوت ، انتقل إلى مستودع GitHub الخاص بك في متصفح الويب الخاص بك ، وانقر فوق علامة الإجراءات. يمكنك معرفة أي سير عمل فشل لأنه يحتوي على شارة تحقق حمراء دائرية عليه. انقر على سير العمل الفاشل لمعرفة سبب الفشل وإصلاحه.

أدناه، يمكنك رؤية أن الفشل يكمن في تنفيذ أوامر SSH عن بُعد باستخدام كلمة مرور. بعد إصلاح سير العمل، عد إلى الخطوة 3 وانظر إذا كان الروبوت يستجيب بـ PONG.

بدء سير عمل إجراءات GitHub من Slack

الآن بعد تنشيط روبوت Slack الخاص بك، حان الوقت لبدء سير عمل إجراءات GitHub من Slack!

تحتاج إلى مرونة لنشر الفرع المعطى إلى خادم معين، مثل سحب الشفرات من الفرع المعطى. ستقوم بتعليم الروبوت للرد تلقائيًا عندما يكتب شخص ما ***@*bot deploy API feature-x to production على قناة Slack. يمكنك التحقق من اسم البيئة حيث يمكن للأشخاص لاحقًا نشر بيئات وفروع معينة فقط.

لتلقيم ردود الروبوت تلقائيًا:

1. أنشئ دليلاً بالاسم ~/Hubot/scripts. المجلد ~/Hubot/scripts هو المكان الذي ستحفظ فيه السكربت الذي يُشغّل سير عمل GitHub الخاص بك.

2. في محرر الشفرة الخاص بك، أنشئ ملفًا بالاسم bot.js داخل المجلد ~/Hubot/scripts. الآن انسخ الشفرة أدناه والصقها داخل ملف bot.js.

الشفرة أدناه تسمح للروبوت بالاستماع إلى رسائل المحادثة على قناة Slack، ثم تُشغّل سير العمل لإرسال استجابة إلى قناة Slack.

const validServices = ['api','app'];
const validEnvironments = ['production'];
robot.hear (`@${process.env.BOT_ID}`,async (bot) => {
    // الروبوت مهتم فقط بسماع الرسائل 
    // مثل @ نشر ميزة api إلى الإنتاج 
    // إعداد متغير قابل لإعادة الاستخدام
	  const payload = bot.message.text.split(" ")
    const service = payload[2];
    const branch = payload[3];
    const environment = payload[5];
    const username = bot.message.user.name;
    // إعلام المستخدم بأننا في صدد المعالجة
    bot.send(`Roger that! Please wait.`);
// التحقق مما إذا كان الأمر الذي تم استخدامه صالحًا أم لا 
// لأن المستخدم قد يستخدم أوامر غير صالحة أيضًا 
if(!validateCommand(bot,username,service,branch,environment)) {
      return;
    }
    // إذا بدا الأمر صالحًا ، فقم بتشغيل سير العمل
    await triggerWorkflow(bot,username,service,environment,branch)
    
    // إعلام المستخدم بأن سير العمل تم تشغيله بنجاح
    bot.send(`Github Action has been triggered successfully`);
  })
  const validateCommand = (bot,username,service,branch,environment) => {
    // حدود الخدمات لأن المستخدمين قد يستخدمون خدمات غير مدرجة 
    // والتي ستحاول تشغيل سير العمل وتحصل على خطأ
    if(!validServices.includes(service)) {
       bot.send(`${service} is not availble, Only ${validServices.join(', ')} are available`);
      return false;
      }
      // حدود البيئة لأن المستخدمين قد يستخدمون قوائم بيئة غير صالحة أيضًا
      if(!validEnvironments.includes(environment)) {
        bot.send(`${environment} is not availble. Only ${validEnvironments.join(', ')} are available`);
        return false;
      }
      return true;
  }

  const triggerWorkflow = (bot,username,service,environment,branch) => {
    try {
      // هذا هو نفس رمز تشغيل سير العمل اليدوي المحول 
      // من curl إلى طلب post جافا سكريبت فعلي
      const data = await axios.post(`https://api.github.com/repos/yourusername/yourreponame/dispatches`,{
        'event_type': 'deploy-service',
        'client_payload': {'environment': environment, 'ref': branch}
      },{headers:{
      Authorization: `token ${token}`,
      }})
    }
      catch(e) {
        bot.send(`Sorry @${username} could not trigger github action. Please check my logs ${e.message}`);
      }
  }

3. أخيرًا ، أرسل الرسالة @ botusername نشر واجهة برمجة التطبيقات إلى التجريبي في سلاك ، وسترى استجابة مماثلة ، كما هو موضح أدناه.

يمكن تنشيط ملفات سير العمل عند حدوث العديد من أحداث GitHub المختلفة، مثل دفع الكود إلى فرع معين، أو إنشاء علامات، أو إنشاء طلبات استحضار، أو طلب بعض عناوين URL، والكثير غيرها.

الختام

خلال هذا البرنامج التعليمي، تعلمت عن سير العمل في GitHub، بدءًا من تنشيط استجابات Slack يدويًا باستخدام الشيفرة إلى بناء روبوت دردشة. كما تعلمت أن وجود روبوت دردشة في Slack يتيح لك أتمتة المهام عن طريق استدعاء سير العمل لإجراءات GitHub.

هل تنوي تعزيز هذه المعرفة الجديدة بخطوة إضافية، ربما بإضافة روبوت تذكير أو إنشاء رسائل تفاعلية؟