إدارة مهام سير العمل وتصحيحها في GitHub Actions

مكتمل

تذكر أن هدفك هو أتمتة عملية إنشاء التعليمات البرمجية ونشرها بحيث يتم تحديث الميزات في كل مرة يضيف فيها المطور تغييرا إلى قاعدة التعليمات البرمجية.

لتنفيذ هذه العملية، ستتعلم كيفية:

• تحديد الحدث الذي أدى إلى تشغيل سير عمل.
• استخدم سجلات سير عمل GitHub Actions.
• حفظ البيانات الاصطناعية للبناء والوصول إليها.
• أتمتة إضافة تسمية إلى طلب سحب بعد المراجعة.

تحديد الحدث الذي أدى إلى تشغيل سير عمل

يعد فهم ما أدى إلى سير عمل GitHub Actions أمرا بالغ الأهمية لتصحيح الأخطاء والتدقيق وتحسين البنية الأساسية لبرنامج ربط العمليات التجارية CI/CD. يتضمن نوع المشغلات دفعة إلى فرع أو طلب سحب تم إنشاؤه أو تحديثه أو مهمة مجدولة أو إرسال يدوي. يمكنك تحديد الحدث المشغل عن طريق فحص تشغيل سير العمل وتغييرات المستودع ومشكلة GitHub ذات الصلة أو طلب السحب.

ما هو مشغل سير العمل؟

مشغل سير العمل هو حدث يتسبب في تشغيل سير عمل. يدعم GitHub أنواعا مختلفة من المشغلات، بما في ذلك:

• push أو pull_request (استنادا إلى تغييرات التعليمات البرمجية)
• workflow_dispatch (مشغل يدوي)
• schedule (وظائف كرون)
• repository_dispatch (أنظمة خارجية)
• أحداث طلب المشكلة والمناقشة والسحب (على سبيل المثال، issues.opened، ) pull_request.closed

تحديد حدث المشغل

يمكنك تحديد حدث مشغل سير العمل بطرق متعددة:

• استخدم واجهة مستخدم إجراءات GitHub:

  1. في المستودع الخاص بك، حدد علامة التبويب الإجراءات .
  2. حدد تشغيل سير عمل.

  يظهر نوع حدث، مثل push، pull_requestأو workflow_dispatch، في أعلى ملخص تشغيل سير العمل.

• استخدم github.event_name في السجلات أو في سير عمل.

  • يعرض GitHub بيانات السياق أثناء تشغيل سير العمل. github.event_name يخبرك المتغير بالحدث الذي قام بتشغيل سير العمل.

  • يمكنك طباعة المعلومات في خطوة لتصحيح الأخطاء:

    -name: Show event trigger
      run: echo "Triggered by ${{ github.event_name }}"
    

• استخدام تفاصيل تشغيل سير العمل:

  • إذا قمت بفحص سير العمل الذي يتم تشغيله برمجيا، مثل استخدام واجهة برمجة التطبيقات، فسيتضمن event كائن التشغيل خاصية تحدد المشغل.
  • يمكنك العثور على خوارزمية التجزئة الآمنة (SHA) والممثل والطوابع الزمنية لتتبع ما تسبب في المشغل.

استنتاج المشغل من تأثيرات المستودع

قد لا يكون لديك حق الوصول المباشر إلى تشغيل سير العمل، ولكنك لا تزال ترغب في استنتاج ما الذي أدى إلى تشغيل سير العمل استنادا إلى نشاط المستودع:

السلوك الملحوظ	حدث الزناد
تم دفع تثبيت جديد إلى main وتم تشغيل سير العمل.	push حدث
تم فتح طلب سحب أو تحديثه.	pull_request حدث
قام المساهم بتشغيل سير عمل يدويا.	workflow_dispatch
يتم تشغيل سير العمل يوميا في وقت محدد.	schedule (كرون)
تم تشغيل سير العمل بعد استدعاء خدمة خارجية.	repository_dispatch
تم تشغيل سير العمل عند إضافة تسمية أو تعليق إلى مشكلة.	issues.* حدث

من خلال مراجعة الطوابع الزمنية ونشاط طلب السحب ومحفوظات التثبيت، يمكنك غالبا تحديد الإجراء الذي تسبب في تشغيل سير العمل.

لتلخيص كيفية تحديد ما الذي أدى إلى تشغيل سير العمل:

• تحقق من ملخص تشغيل سير العمل في علامة التبويب الإجراءات .
• اطبع سير العمل أو سجله github.event_name داخله للرؤية.
• مقارنة الطوابع الزمنية ونشاط المستودع (التثبيتات وطلبات السحب والمشكلات) للاستدلال على المشغل.
• استخدم السياق الكامل event لتحقيق أعمق.

تساعدك هذه الممارسات على تتبع الأخطاء والتدقيق وتحسين موثوقية سير العمل عبر البنية الأساسية لبرنامج ربط العمليات التجارية للتطوير والنشر.

فهم تأثير سير العمل من خلال قراءة ملف التكوين الخاص به

لفهم تأثيرات سير العمل من قراءة ملف التكوين الخاص به، قم بتحليل بنية ومحتويات .yml الملف المخزن في .github/workflows/.

يحدد ملف تكوين سير العمل المعلومات التالية حول سير العمل:

• عند تشغيله (في on القسم).
• ما يفعله (في jobs و steps).
• حيث يتم تشغيله ( runs-on القسم).
• سبب تشغيله (الغرض منه، مثل الاختبار أو النشر أو التحليل).
• كيف يتصرف في ظروف محددة (البيئة، عوامل التصفية، المنطق).

تفسير تأثير سير العمل

1. تحديد المشغل.

   لتحديد الإجراء الذي بدأ سير العمل، راجع on قسم سير العمل.

   على سبيل المثال:

   on:
     push:
       branches: [main]
     pull_request:
       types: [opened, synchronize]
     workflow_dispatch:
   

   سير العمل هذا المثال:

   • يتم تشغيله تلقائيا عند دفع التعليمات البرمجية إلى الفرع الرئيسي (push).
   • يتم تشغيله عند إنشاء طلب سحب أو تحديثه (pull_request).
   • يمكن تشغيله يدويا بواسطة مستخدم (workflow_dispatch).

2. تحديد مهام وخطوات سير العمل.

   لتحديد ما يفعله سير العمل، راجع jobs قسمي سير العمل و steps .

   على سبيل المثال:

   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout code
           uses: actions/checkout@v3
         - name: Install dependencies
           run: npm install
         - name: Run tests
           run: npm test
   

   سير العمل هذا المثال:

   • يستخدم بيئة Linux الظاهرية (runs-on).
   • التحقق من التعليمات البرمجية للمستودع (steps>name).
   • تثبيت تبعيات المشروع (steps>name).
   • تشغيل الاختبارات التلقائية (steps>name).

3. تقييم الغرض من سير العمل ونتائجه.

   من خلال قراءة ملف التكوين، يمكنك وصف النتيجة المقصودة لسير العمل:

   "سير العمل هذا هو مسار تكامل مستمر (CI). يضمن اختبار أي تعليمة برمجية جديدة يتم دفعها إلى المستودع أو إرسالها عبر طلب السحب تلقائيا. إذا فشلت الاختبارات، تعرض واجهة مستخدم سير عمل GitHub هذه النتيجة لمساعدتك في الحفاظ على جودة التعليمات البرمجية."

4. تحديد أو تعيين الميزات الاختيارية التي تؤثر على كيفية تشغيل سير العمل:

   • env تعيين متغيرات البيئة.
   • if يضيف منطق شرطي لتشغيل خطوات محددة فقط عند استيفاء المعايير.
   • timeout-minutes أو continue-on-error تعيين تنفيذ سير العمل ومعالجة الأخطاء.

تشخيص فشل تشغيل سير العمل

1. في المستودع الخاص بك ، انتقل إلى علامة التبويب الإجراءات .

2. ابحث عن التشغيل الفاشل (يشار إليه عادة بعلامة X حمراء).

3. حدد سير العمل الفاشل لفتح ملخص التشغيل.

4. في سجلات سير العمل، راجع الخطأ.

   1. في ملخص التشغيل، قم بتوسيع كل مهمة وخطوة حتى تعثر على المهمة التي تشير إلى الفشل.

   2. حدد الوظيفة أو الخطوة لعرض سجلاتها.

   3. بحث عن:

      • رسائل الخطأ
      • آثار المكدس
      • رموز الخروج

   على سبيل المثال، قد يظهر npm ERR! Test failed اختبار فاشل أو exit code 1.

5. تحقق من ملف تكوين سير العمل.

   .yml استخدم الملف لتحديد:

   • ما الذي كانت تحاول كل خطوة القيام به؟
   • إذا كانت هناك متغيرات البيئة (env) أو الشروط (if) التي تؤثر على التنفيذ.
   • إذا كان الفشل بسبب تبعية مفقودة أو خطأ في بناء الجملة أو خطوة تم تكوينها بشكل خاطئ.

   إذا فشلت خطوة، فتحقق من الأسباب التالية:

   • هل تم تثبيت التبعيات بنجاح في الخطوة السابقة؟
   • هل توجد ملفات الاختبار وتمريرها محليا؟

سيناريوهات الفشل الشائعة

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

Symptom	السبب المحتمل
فشل خطوة وإرجاع command not foundl	التبعية المفقودة أو الإعداد الخاطئ
npm install فشل.	ملف تالف package-lock.json أو مشكلة في الشبكة
فشل خطوة الاختبار	مشكلات اختبار الوحدة أو ملف التكوين المفقود أو بناء جملة اختبار غير صالح
Permission denied يظهر.	أذونات ملف غير صحيحة أو أسرار مفقودة

تحديد كيفية الوصول إلى سجلات سير العمل في GitHub

1. في المستودع الخاص بك ، انتقل إلى علامة التبويب الإجراءات .

2. في قائمة مهام سير العمل، حدد سير العمل ذي الصلة.

   على سبيل المثال، إذا كان الملف .yml يحتوي على التعليمات البرمجية التالية، فسيظهر ارتباط بعنوان CI Workflow في القائمة:

   name: CI Workflow
   

3. حدد تشغيل معين.

   في قائمة عمليات التشغيل التي تعرض الحالة، حدد الطابع الزمني أو رسالة التثبيت الخاصة بالتشغيل المحدد الذي تريد فحصه.

4. قم بتوسيع كل وظيفة وخطوة.

   تعرض صفحة ملخص التشغيل المهام كما تم تعريفها في ملف سير العمل، مثل الإنشاء أو الاختبار:

   1. حدد وظيفة لتوسيعها.
   2. داخل الوظيفة، قم بتوسيع الخطوات الفردية، مثل "تثبيت التبعيات" أو "تشغيل الاختبارات".

5. عرض إخراج السجل.

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

يلخص الجدول التالي الخطوات التي تتخذها للوصول إلى سجلات سير العمل:

Action	Purpose
علامة التبويب الإجراءات	عرض كافة عمليات تشغيل سير العمل.
حدد اسم سير العمل	يتم تشغيل التصفية حسب سير العمل.
تحديد تشغيل	راجع نتائج مهمة وخطوة محددة.
توسيع الخطوات	عرض السجلات التفصيلية.
تنزيل السجلات	قم بتنزيل سجلات لاستكشاف الأخطاء وإصلاحها دون اتصال أو الفريق.

سجلات الإجراءات للبناء

عند تشغيل سير العمل، فإنه ينتج سجلا يتضمن تفاصيل ما حدث وأي أخطاء أو فشل في الاختبار.

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

العمل مع البيانات الاصطناعية

عندما ينتج سير العمل شيئا آخر غير إدخال السجل، يطلق على المنتج اسم أداة ملموسة. على سبيل المثال، ينتج بناء Node.js حاوية Docker التي يمكن نشرها. الحاوية هي أداة يمكنك تحميلها إلى التخزين باستخدام إجراء actions/upload-artifact . يمكنك لاحقا تنزيل الأداة من التخزين باستخدام الإجراءات/download-artifact.

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

تخزين القطع الأثرية

يتم تخزين البيانات الاصطناعية في مساحة تخزين على GitHub. المساحة مجانية للمستودعات العامة، وبعض التخزين مجاني للمستودعات الخاصة، اعتمادا على الحساب. يخزن GitHub البيانات الاصطناعية لمدة 90 يوما.

في قصاصة سير العمل التالية، لاحظ أنه في الإجراء actions/upload-artifact@main توجد سمة path. قيمة هذه السمة هي المسار لتخزين البيانات الاصطناعية. في هذا المثال، يمكنك تحديد public/ لتحميل كل شيء إلى دليل. إذا كنت ترغب في تحميل ملف واحد فقط ، فاستخدم شيئا مثل public /mytext.txt.

  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@main
        with:
          name: webpack artifacts
          path: public/

لتنزيل البيانات الاصطناعية للاختبار، يجب إكمال البناء بنجاح وتحميل البيانات الاصطناعية. في التعليمات البرمجية التالية، يمكنك تحديد أن مهمة الاختبار تعتمد على مهمة البناء.

test:
    needs: build
    runs-on: ubuntu-latest

في قصاصة سير العمل التالية، يمكنك تنزيل البيانات الاصطناعية. الآن يمكن لمهمة الاختبار استخدام الأداة للاختبار.

steps:
    - uses: actions/checkout@v3
    - uses: actions/download-artifact@main
      with:
        name: webpack artifacts
        path: public

لمزيد من المعلومات حول استخدام البيانات الاصطناعية في مهام سير العمل، راجع تخزين بيانات سير العمل كبيانات اصطناعية.

أتمتة المراجعات في GitHub باستخدام مهام سير العمل

بالإضافة إلى بدء سير عمل عبر أحداث GitHub مثل push و pull-request، يمكنك تشغيل سير عمل على جدول زمني أو بعد حدث ما خارج GitHub.

قد ترغب في تشغيل سير عمل فقط بعد أن يكمل المستخدم إجراء معينا، كما هو الحال بعد موافقة المراجع على طلب سحب. لهذا السيناريو، يمكنك تشغيل على pull-request-review.

إجراء آخر يمكنك اتخاذه هو إضافة تسمية إلى طلب السحب. في هذه الحالة، استخدم إجراء pullreminders/label-when-approved-action.

على سبيل المثال:

    steps:
     - name: Label when approved
       uses: pullreminders/label-when-approved-action@main
       env:
         APPROVALS: "1"
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         ADD_LABEL: "approved"

في env الكتلة، يمكنك تعيين متغيرات البيئة للإجراء. على سبيل المثال، يمكنك تعيين عدد الموافقين المطلوبين لتشغيل سير العمل. في هذا المثال، إنه واحد. متغير المصادقة secrets.GITHUB_TOKEN مطلوب لأن الإجراء يجب أن يقوم بإجراء تغييرات على المستودع الخاص بك عن طريق إضافة تسمية. وأخيرا، يمكنك إدخال اسم التسمية لإضافتها.

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