GitHub Actions / المشاركة والسلطة المحدودة / الدرس 11
سير العمل المعاد استخدامه والإجراءات المركبة
اختر حد إعادة استخدام يحفظ عقود التنفيذ والمدخل والمخرج والسلطة.
في هذه الصفحة
أهداف الدرس
- تمييز استدعاء المهمة عن الإجراء داخل الخطوة.
- مراجعة الأنواع والأسرار والمخرجات وهوية الاعتماد.
أعد استخدام الوحدة الصحيحة
يغلف سير العمل القابل لإعادة الاستخدام مهمة أو أكثر ويُستدعى عبر jobs.<id>.uses. ويغلف الإجراء المركب خطوات تعمل داخل مهمة المستدعي. اختر السير عندما تنتمي خيارات المشغلات أو المهام المتعددة أو السياسة بين المهام إلى الوحدة المشتركة. واختر المركب عندما يلزم تتابع متكرر داخل مهمة قائمة. يمكن أن يكون تطبيع تجهيز Parcel مركباً، بينما يناسب رسم تحقق مرشح متعدد المنصات سيراً مشتركاً. ينبغي للمشاركة توضيح المسؤولية والحدود، لا مجرد تقليل عدد الأسطر أو إخفاء سلسلة تنفيذ لا يستطيع المستدعي مراجعتها.
عرّف واجهة صغيرة ذات أنواع
يعلن السير المشترك مدخلات workflow_call وأسراره ومخرجاته وفق المخطط المدعوم. للمدخلات أنواع معلنة مثل boolean وnumber وstring، ويجب أن يرسل المستدعي قيماً مطابقة. اجعل الواجهة ضيقة؛ فقبول برنامج صدفة اعتباطي كمدخل يهدم قدراً كبيراً من فائدة المراجعة. يعلن المقطع وضع تجهيز نصياً ويربط مخرج مهمة بواجهة السير. لا يتضمن المهام المنفذة، ولذلك هو تصور واجهة لا سيراً كاملاً. كما أن النوع string يحدد التمثيل ولا يثبت أن كل قيمة نصية مقبولة في مجال التجهيز.
on:
workflow_call:
inputs:
fixture-mode:
required: true
type: string
outputs:
candidate:
description: Synthetic candidate label
value: ${{ jobs.identify.outputs.candidate }}
يلزم تنفيذ identify ومخرج candidate. لا يتحقق النوع النصي وحده من أسماء التجهيز ولا يفوض هدفاً. لا يُنشأ سير مشترك ولا يستدعى.
للاستدعاء صيغة مهمة مختلفة
ليست المهمة التي تستدعي سيراً عبر uses مهمة runs-on عادية يمكن إلحاق steps بها. لا تقبل إلا الكلمات الموثقة لشكل الاستدعاء. إذا احتجت عملاً لاحقاً فأضف مهمة أخرى تعتمد عليها عبر needs. للمرجع المحلي من المستودع نفسه صيغة نسبية مدعومة، بينما يحتاج المرجع العابر للمستودعات ref صريحاً. ينبغي للاعتماد التشغيلي الإشارة إلى التزام ثابت مراجع لا فرع متحرك غير مراجع. يثبت التثبيت الهوية ولا يضمن السلامة؛ فما زال التنفيذ المثبت وإجراءاته واعتماداته المتداخلة جزءاً من مراجعة الثقة.
مرر السلطة عبر الحد عمداً
تجعل الأسرار المسماة واجهة السلطة ظاهرة، بينما توسع secrets: inherit الترابط الضمني ضمن نطاق المؤسسة أو المشروع المؤسسي المدعوم. فضّل عقداً صريحاً عندما تحتاج سراً واحداً. لا يدعم workflow_call تمرير حقل environment لأسرار البيئة؛ وقد تختار مهمة داخل السير المستدعى بيئتها وأسرارها وفق السلوك الموثق. ولا يستطيع سير متداخل رفع أذونات الرمز ببساطة فوق سلطة المستدعي المسموحة. راجع السلسلة كاملة، بما فيها السحب؛ فالسير المستدعى يعمل بسياق المستدعي ولا يسحب مستودعه الخاص تلقائياً لمجرد أن تعريفه محفوظ فيه.
المركب عقد إجراء
يعلن ملف بيانات المركب runs.using: composite وخطوات منفردة، مع shell صريح لخطوات run. لا ينشئ خدمات حاويات أو مهام مستقلة. مرر المدخلات وتحقق منها، ولا تفترض أن سياق الأسرار واجهة تلقائية عامة؛ فالقيم الحساسة تحتاج تمريراً مقصوداً وفق سياسة المستدعي. يفحص البرنامج المحلي الكامل عقد وضع تجهيز ضيقاً. لا يدقق ملف بيانات Actions ولا ينفذ مركباً ولا يثبت أذونات استدعاء. فائدته إظهار رفض القيم غير المدعومة قبل تحولها إلى مدخل نص برمجي أو مسار ملف يعتمد عليه تنفيذ ذو سلطة.
def validate_mode(value):
if not isinstance(value, str) or value not in {"plain", "unicode"}:
raise ValueError("invalid fixture mode")
return value
for value in ["plain", True]:
try:
print(validate_mode(value))
except ValueError as error:
print(error)
plain
invalid fixture mode
يرفض القيمة المنطقية رغم إمكان تحويلها لنص. لا يحاكي فاحص أنواع GitHub ولا يثبت أذونات الاستدعاء.
الأخطاء الشائعة وإصلاحها
يوضع سير مشترك في uses لخطوة.
- لماذا يحدث؟
- اختلط حد المهمة بحد الإجراء.
- كيف تصلحه؟
- استدعه بصيغة مهمة uses المدعومة.
- كيف تتجنب تكراره؟
- وثق الاستدعاء والتنفيذ للوحدة.
يستخدم المستدعى سر بيئة غير متوقع.
- لماذا يحدث؟
- اختلط اختيار البيئة بالسر الممرر.
- كيف تصلحه؟
- راجع بيئة المهمة وأولوية الأسرار.
- كيف تتجنب تكراره؟
- أظهر السلطة وملكية البيئة بالواجهة.
يغير فرع مشترك متحرك الإصدار بلا مراجعة.
- لماذا يحدث؟
- مرجع الاعتماد متغير.
- كيف تصلحه؟
- اعتمد هوية ثابتة مراجعة وتحديثاً مضبوطاً.
- كيف تتجنب تكراره؟
- راجع الإجراءات والسير المتداخلة ضمن التغيير.
اختبر فهمك
1. تحتاج المشاركة نظامين وتجميعاً لاحقاً. ما الشكل المناسب؟
اعرض الحل المشروح
سير قابل لإعادة الاستخدام يعبر عن المهام والمشغلات. المركب داخل مهمة واحدة ولا يقدم الرسم. ضيق الأنواع والمخرجات ليفهم المستدعي الأدلة.
2. هل يقبل مدخل script أوامر مساهم لأن الغلاف مثبت؟
اعرض الحل المشروح
لا. يحدد التثبيت الغلاف وتغير المدخلات التنفيذية سلوكه وسلطته. فضّل وضعاً صغيراً متحققاً أو إعداداً مراجعاً وأبعد غير الموثوق عن المهمة المميزة.
أهم ما تعلمته
- اختر المشاركة بحد التنفيذ لا تقليل النص فقط.
- تحمل الواجهة عقد بيانات وسلطة.