GitHub Actions / الأحداث والتنفيذ وحدود البيانات / الدرس 2

YAML والسياقات وتقييم التعبيرات

افصل تحليل الإعداد وتوسيع تعبير Actions وتنفيذ الصدفة.

وقت القراءة التقريبي: 4 دقيقةتاريخ مراجعة المحتوى 2026-10-28

في هذه الصفحة

أهداف الدرس

تحديد المفسر المسؤول عن القيمة.
تجنب اعتبار الغائب والنصي قيمة منطقية محددة النوع.

قد تمر ثلاثة مفسرات بسطر واحد

يبدأ التعريف بوصفه YAML، ثم تقيّم GitHub التعبيرات في الحقول المدعومة، ثم ينفذ المشغّل نص الصدفة لاحقاً. قد يصح السطر نحوياً في YAML لكنه يخالف مخطط Actions أو يصبح غير آمن عندما يتحول إلى مدخل صدفة. في Parcel يقيّم مستوى التحكم تعبير اختيار الفرع، بينما توسّع الصدفة $PARCEL_MODE أثناء خطوة run. اسأل أي طبقة تفسر كل جزء قبل إضافة علامات اقتباس. فالاقتباس الذي يحمي بنية YAML لا يحمي بالضرورة القيمة بعد إحلال التعبير داخل برنامج الصدفة، ولكل طبقة قواعد مستقلة.

تتوفر السياقات في أوقات مختلفة

يصف سياق github معلومات الحدث والتشغيل، ويصف runner المشغّل المختار، ويصف matrix عنصر المصفوفة بعد توسيعها، وتعرض needs معلومات الاعتمادات المعلنة. يختلف توفر السياق باختلاف الحقل ومرحلة التنفيذ. لا يستطيع شرط على مستوى المهمة قراءة ملف ستنتجه خطوة لم تعمل بعد. توجد متغيرات البيئة الافتراضية على المشغّل، بينما يمكن استخدام بعض السياقات أثناء قرارات التوجيه السابقة له حيث تسمح المنصة. راجع جدول توفر السياقات للحقل المحدد بدلاً من افتراض أن كل قيمة قانونية في كل موضع من التعريف.

قد تضلل الخصائص المفقودة

عند الإشارة إلى خاصية سياق غير موجودة تنتج قيمة نصية فارغة. كما أن مخرجات الخطوات نصوص ما لم تُحوّل صراحة، وقد يختلف النص false عن القيمة المنطقية false عند التقييم. حدّد النوع المتوقع وتحقق منه قبل استخدامه في قرار إصدار. يوضح برنامج Python الكامل الفرق بين النص وقيمة JSON المحللة فقط، ولا يحاكي قواعد التحويل الضمني في GitHub. ارجع إلى مرجع التعبيرات لدلالات المساواة والصدق والتحويل الخاصة بـ Actions، ولا تنقل قواعد لغة مألوفة إليها دون مراجعة.

python يختلف النص عن قيمة منطقية محللة

import json
text = "false"
value = json.loads(text)
print(type(text).__name__)
print(type(value).__name__)
print(value is False)

الناتج المتوقع

str
bool
True

تسمى القيمة المنطقية في Python bool. يثبت المثال فرق النوع ونتيجة JSON لا دلالة كل مشغّل في GitHub.

انقل البيانات عبر حدود البيئة

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

yaml نقل السياق إلى البيئة

env:
  PARCEL_REF: ${{ github.ref }}
steps:
  - name: Display selected ref
    shell: bash
    run: printf "%s\n" "$PARCEL_REF"

جزء مهمة لا سير كامل. صيغة printf ثابتة والقيمة وسيط مقتبس. يعتمد المرجع على الحدث فلا نقدّم نتيجة تشغيل مختلقة.

راجع الشرط بحالات سلبية

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

الأخطاء الشائعة وإصلاحها

يُستخدم متغير صدفة لتوجيه المهمة.

لماذا يحدث؟: اختلط وقت العامل بتقييم مستوى التحكم.
كيف تصلحه؟: استخدم سياقاً مدعوماً للحقل.
كيف تتجنب تكراره؟: وضح وقت توفر القيمة.

يفعل النص false فرعاً منطقياً.

لماذا يحدث؟: عومل المخرج النصي كقيمة منطقية.
كيف تصلحه؟: قارن أو حلل وفق قواعد Actions صراحة.
كيف تتجنب تكراره؟: حدد النوع واختبر الفارغ والخاطئ والتالف.

تُعد اقتباسات YAML منعاً للحقن.

لماذا يحدث؟: يحدث الإحلال قبل تفسير الصدفة.
كيف تصلحه؟: مرر غير الموثوق كبيانات بواجهة مراجعة.
كيف تتجنب تكراره؟: راجع طبقات التفسير الثلاث.

اختبر فهمك

1. تكتب خطوة ready. هل يقرؤه شرط المهمة السابق؟

اعرض الحل المشروح

لا. لم تنفذ الخطوة عند اختيار المهمة. انقل القرار لخطوة لاحقة أو أعلن مخرج مهمة منتجة واستهلكه عبر needs. احترم التوفر بدلاً من تغيير الاقتباس.

2. لماذا لا يحاكي مثال Python تعبيرات Actions؟