تكوين سير عمل إجراءات GitHub

مكتمل

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

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

كما ذكرنا سابقا، يمكنك تكوين مهام سير العمل الخاصة بك لتشغيلها عند حدوث نشاط معين على GitHub أو عند حدوث حدث خارج GitHub أو في وقت مجدول. يسمح لك الحدث schedule بدفع سير العمل للتشغيل في أوقات UTC معينة باستخدام بنية POSIX cron . تحتوي بنية cron هذه على خمسة * حقول ويمثل كل حقل وحدة من الوقت.

على سبيل المثال، إذا كنت تريد تشغيل سير عمل كل 15 دقيقة، schedule فسيبدو الحدث مثل المثال التالي:

on:
  schedule:
    - cron:  '*/15 * * * *'

وإذا كنت تريد تشغيل سير العمل في كل يوم أحد في الساعة 3:00 بالضبط، فسوف يبدو الحدث schedule على هذا النحو:

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

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

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

علاوة على الأحداث المجدولة، يمكنك تشغيل سير العمل يدوياً باستخدام الحدث workflow_dispatch. يسمح لك هذا الحدث بتشغيل سير العمل باستخدام GitHub REST API أو عن طريق تحديد الزر Run workflow في علامة التبويب Actions داخل المستودع الخاص بك على GitHub. باستخدام workflow_dispatch، يمكنك اختيار الفرع الذي تريد تشغيل سير العمل عليه، وتعيين اختياري inputs يقدمه GitHub كعناصر نموذج في واجهة المستخدم.

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'  

إضافة إلى workflow_dispatch، يمكنك استخدام GitHub API لتشغيل حدث خطاف ويب يُطلق عليه repository_dispatch. يسمح لك هذا الحدث بتشغيل سير عمل للنشاط الذي يحدث خارج GitHub. وهو يعمل بشكل أساسي كطلب HTTP إلى المستودع الخاص بك يطلب من GitHub تشغيل سير عمل خارج إجراء أو إخطار على الويب. يتطلب استخدام هذا الحدث اليدوي القيام بأمرين: إرسال POST طلب إلى نقطة نهاية GitHub /repos/{owner}/{repo}/dispatches مع أسماء أحداث إخطار على الويب في نص الطلب، وتكوين سير العمل لاستخدام الحدث repository_dispatch.

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/dispatches \
  -d '{"event_type":"event_type"}'

on:
  repository_dispatch:
    types: [opened, deleted]

تكوين مهام سير العمل لأحداث خطاف الويب

أخيرا، يمكنك تكوين سير عمل للتشغيل عند حدوث أحداث خطاف ويب معينة على GitHub. يمكنك تشغيل معظم أحداث خطاف الويب من أكثر من نشاط واحد لخطاف الويب. إذا كانت هناك أنشطة متعددة لخطاف الويب، يمكنك تحديد نوع نشاط لتشغيل سير العمل. على سبيل المثال، يمكنك تشغيل سير عمل للحدث check_run ، ولكن فقط لنوعي rerequested النشاط أو requested_action .

on:
  check_run:
    types: [rerequested, requested_action]

Repository_dispatch

repository_dispatch هو حدث مخصص في GitHub Actions يسمح للأنظمة الخارجية (أو حتى مهام سير عمل GitHub الأخرى) بتشغيل مهام سير العمل يدويا عن طريق إرسال طلب POST إلى واجهة برمجة تطبيقات GitHub. وهو يتيح الأتمتة والتكامل المرن مع الأدوات الخارجية أو البرامج النصية أو الأنظمة التي تحتاج إلى بدء مهام سير العمل في المستودع الخاص بك.

حَالات الاستخدَام

• تشغيل مهام سير العمل من أدوات CI/CD الخارجية.

• تنسيق عمليات النشر متعددة المستودع (على سبيل المثال، ينتهي Repo A من بناء → مشغلات Repo B).

• ابدأ التشغيل التلقائي استنادا إلى الأحداث الخارجية (الإخطارات على الويب، ومراقبة التنبيهات، ووظائف CRON خارج GitHub).

• سلسلة عمليات تنفيذ سير العمل بين المستودعات أو داخل المستودعات.

مثال على سير العمل الذي يستمع إلى repository_dispatch

name: Custom Dispatch Listener

on:
  repository_dispatch:
    types: [run-tests, deploy-to-prod]  # Optional filtering

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Echo the payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload value: ${{ github.event.client_payload.env }}"

العناصر الرئيسية:

• أنواع: اختياري. تعريف أنواع الأحداث المخصصة مثل run-tests، deploy-to-prod، وما إلى ذلك.

• github.event.client_payload: الوصول إلى أي بيانات مخصصة أخرى تم تمريرها في حدث الإرسال.

• github.event.action: اسم event_type المرسلة.

تشغيل الحدث عبر واجهة برمجة التطبيقات

يجب إرسال طلب POST إلى نقطة نهاية GitHub REST API v3:

POST https://api.github.com/repos/OWNER/REPO/dispatches

التصريح

• يتطلب رمز وصول شخصي (PAT) مع نطاق المستودع.
• بالنسبة للمؤسسات، تأكد من إعدادات الوصول المناسبة للرمز المميز الخاص بك.

نموذج بنية الأوامر

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"run-tests","client_payload":{"env":"staging"}}'

هيكل الحمولة

{
  "event_type": "run-tests",
  "client_payload": {
    "env": "staging"
  }
}

المعلمات

الحَقل	النَوع	‏‏الوصف	المطلوب
event_type	خيط	اسم مخصص للحدث. يعين هذا الاسم إلى قيمة الأنواع في مشغل سير العمل	نعم
client_payload	كائن	حمولة JSON العشوائية لإرسال بيانات مخصصة إلى سير العمل (github.event.client_payload)	لا

تصنيف المعلمات Repository_dispatch

عند إجراء طلب POST إلى نقطة نهاية GitHub API، يجب تمرير نص JSON مع معلمتين رئيسيتين:

• event_type
• client_payload

event_type

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

• التنسيق:

  • النوع: سلسلة
  • مثال: "deploy" و"run-tests" و"sync-db" و"build-docker"

• الاستخدام في سير العمل: يستخدم في الاستماع إلى أنواع أحداث معينة والوصول إلى القيمة داخل سير العمل. يساعد هذا في إعادة استخدام سير عمل واحد لأغراض متعددة ويجعل الأتمتة أكثر تنظيما ومحركا للحدث.

• مثال:

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"

client_payload

كائن JSON حر النموذج يتيح لك إرسال بيانات مخصصة مع الإرسال. يمكنك تحديد البنية، ويمكن الوصول إليها داخل سير العمل.

• التنسيق:

  • النوع: كائن
  • المفاتيح والقيم المخصصة

• الاستخدام في سير العمل: يستخدم هذا الكائن في عمليات النشر متعددة البيئة أو الإصدارات التي تم إصدارها أو تمرير السياق من نظام أو مسار آخر ويمكن مهام سير العمل ذات المعلمات، على غرار وسيطات الإدخال.

• مثال:

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"

مثال على تصنيف البيانات الأساسية

{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

استخدام كلمات أساسية شرطية

ضمن ملف سير العمل الخاص بك، يمكنك الوصول إلى معلومات السياق وتقييم التعبيرات. على الرغم من أن التعبيرات يشيع استخدامها مع الكلمات الأساسية if الشرطية في ملف سير العمل لتحديد ما إذا كان يجب تشغيل الخطوة أم لا، إلا إنه يمكنك استخدام أي سياق وتعبير معتمدين لإنشاء أي شرط. من المهم معرفة أنه عند استخدام الشروط في سير العمل الخاص بك، تحتاج إلى استخدام بناء الجملة ${{ <expression> }}المحدد . يخبر بناء الجملة هذا GitHub بتقييم تعبير بدلا من معاملته كسلسلة.

على سبيل المثال، سير العمل الذي يستخدم if الشرطي للتحقق مما إذا كان github.ref (الفرع أو مرجع العلامة الذي قام بتشغيل سير العمل) يطابق refs/heads/main. من أجل المتابعة، سيبدو سير العمل كما يلي:

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      ...

لاحظ في هذا المثال أن ${{ }} مفقود من البنية. مع بعض التعبيرات، مثل if الشرطي، يمكنك حذف بناء جملة التعبير. يقوم GitHub تلقائياً بتقييم بعض هذه التعبيرات الشائعة، لكن يمكنك دائماً تضمينها في حال نسيان التعبيرات التي يقيمها GitHub تلقائياً.

لمزيد من المعلومات حول بنية سير العمل وتعبيراته، راجع بنية Workflow لـ GitHub Actions.

تعطيل عمليات سير العمل وحذفها

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

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

• ينتج أي خطأ في سير العمل طلبات كثيرة جدا أو طلبات خاطئة تؤثر سلبا على الخدمات الخارجية.
• تريد إيقاف سير عمل غير هام مؤقتا ويستغرق دقائق كثيرة جدا على حسابك.
• تريد إيقاف سير عمل يرسل طلبات إلى خدمة معطلة مؤقتا.
• أنت تعمل على نسخة المستودع، ولا تحتاج إلى جميع وظائف بعض مهام سير العمل التي يتضمنها (مثل مهام سير العمل المجدولة).

يمكنك أيضا إلغاء تشغيل سير عمل قيد التقدم في واجهة مستخدم GitHub من علامة التبويب Actions أو باستخدام نقطة DELETE /repos/{owner}/{repo}/actions/runs/{run_id}نهاية GitHub API . ضع في اعتبارك أنه عند إلغاء تشغيل سير عمل، يقوم GitHub بإلغاء جميع وظائفه وخطواته ضمن هذا التشغيل.

استخدام سير عمل مؤسسة تم إعداد قالب له

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

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

استخدام إصدارات محددة من أي إجراء

عند الرجوع إلى الإجراءات في سير العمل الخاص بك، نوصي بالإشارة إلى إصدار معين من هذا الإجراء بدلا من الإجراء نفسه فقط. بالرجوع إلى إصدار معين، فإنك تضع حماية من التغييرات غير المتوقعة التي يتم دفعها إلى الإجراء الذي قد يؤدي إلى تعطيل سير العمل الخاص بك. فيما يلي عدة طرق يمكنك من خلالها الرجوع إلى إصدار معين من الإجراء:

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

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