GitHub Actions Workflow Lockfiles: دليل عملي لتأمين تبعيات CI/CD
تعرف إلى ملفات قفل تبعيات GitHub Actions، وكيفية إنشاء actions.lock ومراجعته وصيانته مع Dependabot للحد من مخاطر تغيّر الوسوم والفروع.
قد يبدو ملف GitHub Actions ثابتًا بعد مراجعته ودمجه، لكن هناك تفصيلًا مهمًا قد لا يظهر في مراجعة الشيفرة: المرجع الذي يستخدمه سير العمل لتحديد أحد الإجراءات قد يتغير لاحقًا. فإذا اعتمد الملف على وسم مثل v3 أو فرع مثل main، فقد يشير المرجع نفسه في تشغيل مستقبلي إلى commit مختلف عن الذي راجعته سابقًا.
هنا تأتي أهمية GitHub Actions Workflow Lockfiles. أعلنت GitHub إتاحة ملفات قفل تبعيات سير العمل في المعاينة العامة يوم 14 أكتوبر 2026 لمستخدمي GitHub Enterprise Cloud، بما في ذلك نسخة الإقامة الجغرافية للبيانات. تساعد هذه الميزة على ربط التبعيات بـcommits محددة وجعل تغييراتها قابلة للمراجعة بدل الاعتماد على وسوم أو فروع متحركة وحدها.
ما المقصود بـ Workflow Lockfiles؟
ملف القفل هو سجل للتبعيات التي يستخدمها سير العمل، مع تحديد commit الذي جرى تثبيته لكل تبعية. في GitHub Actions، قد يحتوي ملف YAML على إجراءات خارجية أو يستدعي سير عمل قابلًا لإعادة الاستخدام. مثال بسيط:
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4هذه الصيغة واضحة وسهلة القراءة، لكن الوسم مثل v4 ليس هوية ثابتة للشيفرة؛ يمكن أن يتحرك إلى commit آخر. يضيف ملف القفل سجلًا يحدد الـcommit الذي تمت مراجعته، مع معلومات عن هوية المستودع المصدر.
يُحفظ الملف في المسار .github/workflows/actions.lock ويُنشأ بواسطة إضافة GitHub CLI المسماة gh actions-lock. الملف مولّد آليًا، لذلك لا ينبغي تحريره يدويًا. عند تهيئة سير عمل لاستخدام القفل، يجب أن تكون تبعيات الإجراءات المطلوبة مسجلة فيه، ويستخدم GitHub Actions الـcommits المقفلة بدل حل الوسم المتحرك عند كل تشغيل.
لماذا قد تكون الوسوم والفروع المتحركة مشكلة؟
تساعد الوسوم مثل @v2 والفروع مثل @main على إبقاء ملفات سير العمل قصيرة، لكنها قد تتغير بعد مراجعة الشيفرة. تخيل أن فريقك راجع إجراءً ودمجه في بيئة الإنتاج، ثم أعاد مالك المستودع المصدر توجيه الوسم إلى commit مختلف. قد ينفذ التشغيل التالي شيفرة لم يراجعها فريقك، حتى لو لم يتغير ملف YAML في مستودعك.
قد يكون تغيير المرجع مشروعًا ويحتوي على إصلاحات مهمة، لكن الخطر يكمن في أن التغيير قد يحدث من دون تعديل ظاهر في مستودعك. وإذا تعرض حساب مالك الإجراء للاختراق، فقد يستغل المهاجم الوسم المتحرك لتقديم شيفرة ضارة. يساعد القفل على منع هذا التغيير غير المتوقع من المرور بصمت.
مع ذلك، لا تثبت ملفات القفل أن الإجراء آمن بحد ذاته. إنها تساعد على ضمان أن الشيفرة التي يجري تنفيذها هي الشيفرة التي ثبّتها الفريق، لذلك تظل مراجعة المصدر والصلاحيات وتحديثات الأمان ضرورية.
ما الذي يسجله ملف actions.lock؟
يتضمن الملف قسمين أساسيين. يسجل قسم workflows ملفات سير العمل التي جرى تهيئتها والتبعيات التي يستخدمها كل ملف. أما قسم dependencies فيربط مرجع كل تبعية بالـcommit المحدد، إلى جانب معلومات مثل معرّف مالك المستودع ومعرّف المستودع نفسه. تساعد هذه المعلومات GitHub على التحقق من أن الاسم ما زال يشير إلى المستودع الذي جرى تثبيته.
تغطي الآلية تبعيات الإجراءات المتداخلة أيضًا، أي الإجراءات التي يعتمد عليها إجراء آخر. أما تبعيات سير العمل القابل لإعادة الاستخدام، فيجب الانتباه إلى أن القفل الذي يغطيه هو القفل الموجود في المستودع الذي يعرّف سير العمل القابل لإعادة الاستخدام. إذا كانت مؤسستك تدير سير عمل مشتركًا، فابدأ بتهيئة مستودعاته ومراجعتها أيضًا.
إعداد Workflow Lockfiles خطوة بخطوة
1. راجع مراجع الإجراءات الحالية
قبل إنشاء الملف، افحص ملفات YAML داخل .github/workflows/ وتأكد من أن كل مرجع uses يشير إلى إصدار تريد تثبيته. راجع مصدر الإجراء وسجل تغييره، ولا تثبّت التبعيات بشكل آلي قبل التأكد من أنها النسخ المقصودة. توصي GitHub أيضًا بتفعيل Dependabot لإدارة تحديثات الإجراءات قبل البدء، حتى لا تصبح التبعيات المقفلة قديمة دون متابعة.
2. ثبّت GitHub CLI والإضافة
تحتاج إلى GitHub CLI المعروف بالأمر gh. بعد تثبيته وتسجيل الدخول حسب متطلبات بيئتك، ثبّت الإضافة الرسمية:
gh extension install github/gh-actions-lockلمعرفة الخيارات المتاحة في النسخة المثبتة، استخدم:
gh actions-lock --helpولترقية الإضافة مستقبلًا، يمكنك استخدام gh extension upgrade gh-actions-lock. وبما أن الميزة في المعاينة العامة، راجع الوثائق الرسمية دوريًا للتحقق من تغير الخيارات أو المتطلبات.
3. أنشئ ملف القفل
من جذر المستودع، شغّل الأمر التالي لمعالجة ملفات سير العمل الموجودة:
gh actions-lockتستعرض الإضافة ملفات سير العمل تحت .github/workflows/ وتحاول تثبيت الإجراءات القابلة للحل على commits محددة، ثم تكتب ملف القفل وتعدّل بعض مراجع uses لتصبح أكثر تحديدًا. إذا أردت تهيئة سير عمل واحد فقط، مرّر مساره بدلًا من معالجة المجلد كله:
gh actions-lock .github/workflows/ci.ymlاستبدل ci.yml باسم ملف موجود فعلًا في مشروعك. إذا أبلغت الإضافة عن مسار محلي غير مدعوم، فتحقق من مرجع الإجراء المحلي؛ فالمسارات المحلية تُحل انطلاقًا من جذر المستودع.
4. راجع التغييرات قبل الالتزام بها
لا تتعامل مع الملف المولد على أنه ملف ثانوي يمكن قبوله دون مراجعة. افحص كل التغييرات باستخدام:
git status
git diffراجع ملف القفل وملفات سير العمل معًا. قد يتحول مرجع مثل octo-org/deploy-action@v3 إلى إصدار أكثر تحديدًا مثل @v3.1.0، بينما يسجل القفل الـcommit الذي سيُنفذ. افحص أي تغيير في commit أو هوية المستودع المصدر، وتأكد من أن سياسات السماح بالإجراءات في مؤسستك متوافقة مع المراجع المقفلة.
بعد مراجعة الفرق، سجّل التغييرات في commit وافتح Pull Request ليتمكن الفريق من مراجعتها. تعامل مع تغيير commit على أنه تحديث للتبعية قد يغير الشيفرة المنفذة، وليس مجرد تعديل تنسيقي.
5. تحقق من أن الملف محدث
يجب إعادة تشغيل الإضافة عند إضافة سير عمل يستخدم إجراءات أو عند إضافة تبعيات أو حذفها من ملف موجود. وللتحقق من أن القفل محدث من دون تعديل الملفات، استخدم:
gh actions-lock --verifyيمكن إدراج هذا الفحص في CI ليكشف عن ملف قفل قديم أثناء مراجعة Pull Request. وتوثق الإضافة كذلك خيار --verify-local --no-fix للاستخدام في hook محلي قبل الـcommit؛ يعمل هذا الفحص دون اتصال ولا يعيد التحقق من التثبيتات عبر GitHub.
كيف يساعد Dependabot؟
يستطيع Dependabot إدارة تحديثات إصدارات GitHub Actions. عندما يفتح تحديثًا لإجراء في سير عمل تمت تهيئته بالفعل لاستخدام ملف القفل، فإنه يحدّث مدخل القفل المقابل في Pull Request نفسه، لتظل مرجعية سير العمل والـcommit المسجل متوافقين.
لكن Dependabot لا يهيئ سير عمل جديدًا للقفل من تلقاء نفسه. إذا وجد تبعية في سير عمل لم تتم تهيئته، فسيتطلب الأمر إعداد القفل أولًا. لذلك ابدأ بإنشاء ملف القفل ومراجعة سير العمل، ثم استخدم Dependabot لصيانة تحديثات التبعيات. بهذه الطريقة تصبح التحديثات جزءًا من مسار المراجعة المعتاد بدل أن تتراكم بصمت.
ملفات القفل أم تثبيت SHA داخل YAML؟
توصي ممارسات GitHub الأمنية التقليدية بتثبيت إجراءات الطرف الثالث على SHA كامل للـcommit داخل ملف سير العمل. أما عند اعتماد Workflow Lockfiles، فيمكن الاحتفاظ بمراجع إصدارات مقروءة في YAML وتسجيل commits الدقيقة في ملف القفل. وتغطي الآلية التبعيات المتداخلة، وهو أمر لا توفره كتابة SHA لكل إجراء مباشر وحده.
لا يعني ذلك أن كل مشروع يجب أن يغيّر إعداداته فورًا. تحقّق من توفر الميزة في حسابك، وراجع سياسات السماح بالإجراءات وقواعد الحماية، واختبر التوافق قبل تعميمها. يمكن أيضًا الإبقاء على سياسة اشتراط SHA كامل للإجراءات التي لم تُغطَّ بعد بملف قفل.
حدود ونصائح قبل اعتماد الميزة
- الميزة في المعاينة العامة: قد تتغير التفاصيل، لذا تابع الوثائق الرسمية قبل اعتمادها كسياسة ثابتة.
- القفل ليس فحصًا للثغرات: يحدد الشيفرة المنفذة لكنه لا يثبت خلوها من العيوب أو السلوك الضار.
- المراجعة لا تزال أساسية: تغيّر commit أو معرّف المستودع يستحق التحقيق قبل الدمج.
- أبقِ الملف محدثًا: أضف فحص
gh actions-lock --verifyإلى CI، وفكر في hook محلي لتقليل الأخطاء قبل الـcommit. - قلّل الصلاحيات: امنح
GITHUB_TOKENالحد الأدنى المطلوب، ولا تعرض الأسرار لإجراءات لا تحتاجها. - ابدأ تدريجيًا: جرّب الميزة على مجموعة محدودة من سير العمل، ثم وسّعها بعد مراجعة النتائج.
تتيح GitHub أيضًا سياسة Require lockfile لفرض استخدام ملفات القفل على مستوى المستودع أو المؤسسة أو المؤسسة الكبرى. من الأفضل البدء بالتقييم والنطاق المحدود والتأكد من أن الملفات محدثة قبل تفعيل سياسة تمنع تشغيل سير عمل غير مهيأ.
أسئلة شائعة
هل تلغي ملفات القفل الحاجة إلى مراجعة الإجراءات؟
لا. هي تساعد على تشغيل الـcommit الذي جرى تثبيته، لكنها لا تحدد ما إذا كانت الشيفرة موثوقة أو آمنة. راجع المصدر والتغييرات والصلاحيات باستمرار.
هل يمكن لأي حساب GitHub استخدام الميزة؟
أُعلنت الميزة في المعاينة العامة لمستخدمي GitHub Enterprise Cloud، بما في ذلك خيار إقامة البيانات. تحقق من وثائق GitHub لمعرفة شروط الإتاحة الحالية لحسابك.
هل يقوم Dependabot بإنشاء ملف القفل من الصفر؟
لا. يساعد على تحديث مدخل القفل عندما يحدّث إجراء في سير عمل مهيأ بالفعل. تحتاج إلى تهيئة سير العمل أولًا.
هل أعدل actions.lock يدويًا؟
لا. الملف مولّد بواسطة الأداة. عدّل مراجع سير العمل عند الحاجة، ثم أعد تشغيل gh actions-lock وراجع الفرق الناتج.
الخلاصة
تساعد GitHub Actions Workflow Lockfiles على تثبيت تبعيات CI/CD على commits محددة، والحد من مخاطر تغيّر الوسوم والفروع بعد مراجعة سير العمل. وتزداد فائدتها عندما تُستخدم مع مراجعة تغييرات القفل، وDependabot، وفحوص CI التي تكشف الملفات القديمة، وسياسات صلاحيات واضحة.
ابدأ بمراجعة التبعيات الحالية، وثبّت الإضافة الرسمية، وأنشئ ملف القفل، ثم افحص جميع التغييرات قبل الدمج. والأهم من إنشاء الملف هو الحفاظ على تحديثه ومراجعة كل تغيير فيه باعتباره تغييرًا في الشيفرة التي ستعمل داخل بيئة البناء أو النشر.