ملف القفل في GitHub Actions يثبّت كود التنفيذ، لا منظومة CI بأكملها

هل يمكن الوثوق بـ GitHub Actions عندما يشير workflow إلى action عبر وسم مثل @v3؟ يحدّد ملف القفل أي commit من action سيُنفّذ، حتى لو نُقل الوسم لاحقًا. ويمكن للفريق مراجعة تحديثات التبعيات في diff والاحتفاظ بقائمة قابلة للتحقق من actions التي يستخدمها CI. أما الحد العملي، فهو أن ملف القفل يشمل actions التي تستدعيها الخطوات، بينما يجب تثبيت سير العمل القابل لإعادة الاستخدام، المستدعى على مستوى job، على نحو منفصل. الآلية الموضحة متاحة في GitHub Enterprise Cloud.

ما الذي يثبّته ملف القفل تحديدًا؟

الروابط إلى الفروع والوسوم مريحة، لكن النسخة التي تشير إليها قد تتغير. يشير سطر مثل uses: octo-org/deploy-action@v3 إلى اسم وسم؛ ويحلّ GitHub هذا الرابط إلى commit عند التشغيل. وإذا نقل مالك المشروع الوسم، فقد يحصل التشغيل التالي على كود مختلف ما لم تكن التبعية مثبتة.

وفقًا لوثائق GitHub حول ملفات القفل، يخزّن الملف .github/workflows/actions.lock روابط التبعيات وcommit SHA المقابلة لها، بما فيها التبعيات الانتقالية، أي actions التي تستخدمها actions أخرى. وينشئ الملف امتداد GitHub CLI المسمى gh actions-lock؛ ولا يُعدّل يدويًا.

يمكن للمولّد أيضًا تنقيح روابط uses في ملفات workflow؛ فمثلًا، يمكنه جعل الرابط إلى وسم متحرك أكثر تحديدًا، مع الاحتفاظ بالـ commit الذي أشار إليه عند إنشاء ملف القفل. لذلك ينبغي عند تطبيق الآلية مراجعة diff كاملًا، بما يشمل تغييرات workflow وملف القفل، والتحقق من أن النسخة المثبتة هي النسخة التي يعتزم الفريق تشغيلها.

بعد ذلك، يصبح تحديث التبعية تغييرًا ظاهرًا في المستودع: يمكن للفريق مراجعة تغيير commit ومناقشته واعتماده عبر عملية المراجعة المعتادة. يساعد ملف القفل على تدقيق كود actions والحفاظ على اتساق التبعيات؛ لكنه لا يثبت بمفرده أن الكود المختار آمن.

أين تنتهي حدود التثبيت؟

لا يثبّت ملف القفل في المستودع المستدعي سيرَ العمل القابل لإعادة الاستخدام، عندما يكون الاستدعاء ضمن jobs.<job_id>.uses. فتبعيات سير العمل القابل لإعادة الاستخدام تخص المستودع الذي عُرّف فيه ذلك السير. ولتثبيت الاستدعاء نفسه، حدّد commit SHA كاملًا؛ أما تثبيت actions الخاصة به، فيتطلب ملف قفل مستقلًا في المستودع المصدر.

يضبط ملف القفل كود actions، لكنه لا يضبط مدخلات البناء الأخرى، مثل المعلمات الممررة إلى action أو الأسرار أو صورة runner. وهو يجيب عن سؤال محدد: أي commit من كود action سيُنفّذ؟ أما هذه العناصر الأخرى فتحتاج إلى قواعد إدارة خاصة بها.

وهناك حالة خاصة أيضًا: action محلي يُستدعى عبر مسار مثل uses: ./. ووفقًا لتعليمات GitHub، لا يثبّت امتداد gh actions-lock مسار action المحلي ولا يحلله. وإذا كان هذا action يستخدم actions أخرى، فيجب إدارة التبعيات بصورة منفصلة؛ وتشرح الوثائق خيار نقل روابط actions المحلية إلى صيغة $ /.

وعليه، قد يكون إدخال واحد في ملف القفل جزءًا من سلسلة، لكنه لا يحل محل ضبط جميع حلقاتها. بالنسبة إلى سير عمل خارجي قابل لإعادة الاستخدام، تحقّق من تثبيت الاستدعاء ومن حالة المستودع المصدر؛ وبالنسبة إلى actions المحلية، تحقّق من طريقة احتساب تبعياتها.

كيف تطبّق الضوابط من دون إيقاف CI فجأة؟

توصي GitHub ببدء تجربة أولية على مستودعات وملفات workflow مختارة. تمنع سياسة Require lockfile تشغيل ملفات workflow المستهدفة من دون ملف قفل صالح، بما في ذلك ملفات workflow التي لا تتضمن تبعيات uses:. ولا يتوفر وضع Evaluate للسياسات إلا في GitHub Enterprise Cloud. لذا، هيّئ نطاق التطبيق والتحديثات الآلية أولًا، ثم فعّل القاعدة الإلزامية.

1. تحقّق من الروابط الأصلية. قبل إنشاء ملف القفل، تأكد من أن actions تشير إلى إصدارات يريد الفريق تثبيتها فعلًا. يثبّت المولّد الـ commit الذي يحلّ إليه الرابط الحالي.
2. أنشئ ملف القفل وراجعه. ثبّت امتداد gh-actions-lock، وشغّل gh actions-lock من جذر المستودع، وراجع diff كاملًا، بما في ذلك روابط uses التي أُعيدت كتابتها.
3. أعدّ التحديث والتحقق. يمكن لـ Dependabot تحديث الإدخالات المناسبة لملفات workflow المهيأة مسبقًا. وفي CI، يمكن إعداد مهمة تحقق لطلبات السحب باستخدام gh actions-lock --verify لاكتشاف ملفات القفل القديمة قبل عملية البناء الأساسية.
4. حدّد المراجعين. أضف .github/workflows/actions.lock إلى CODEOWNERS، واشترط مراجعة التغييرات من المسؤولين عن أمن البناء.
5. اختبر السياسة أولًا. ابدأ بالمستودعات وملفات workflow المهيأة. حلّل النتائج في وضع Evaluate، وتحقق قبل الانتقال إلى وضع Active من جاهزية جميع ملفات workflow المستهدفة ومن بقاء ملفات القفل محدثة.

إن Require lockfile وسياسة Require actions to be pinned to a full-length commit SHA قاعدتان مختلفتان؛ وتشير GitHub إلى إمكان الإبقاء عليهما معًا. كما تؤدي عملية التحقق في CI والسياسة الإلزامية دورين مختلفين: الأولى تكشف الملف القديم أثناء العمل على طلب السحب، والثانية تمنع تشغيل workflow غير المستوفي للشرط.

مثال: تحديث action للنشر

لنفترض أن workflow ينشر تطبيقًا عبر octo-org/deploy-action@v3. يتحقق الفريق أولًا من الإصدار الذي يحلّ إليه الرابط، ثم يشغّل gh actions-lock ويراجع diff الخاص بـ workflow إلى جانب إدخال commit في ملف القفل. وعند تحديث action، يرى المراجع تغييرات الروابط والـ commit المثبت؛ ما يتيح له تقييم التحديث المحدد بدلًا من افتراض أن الوسم المتحرك سيظل يشير إلى الكود نفسه.

إذا كان النشر ينفّذ سير عمل قابلًا لإعادة الاستخدام من مستودع آخر، فلن يشمل ملف القفل المحلي تبعياته. ثبّت رابط سير العمل القابل لإعادة الاستخدام باستخدام SHA كامل، وتحقق من أن المستودع المصدر يدير تبعيات actions الخاصة به. وفي المؤسسات الكبيرة، يحوّل ذلك القواعد المتفرقة إلى عملية قابلة للتحقق، مع الإبقاء على ضوابط منفصلة للمعلمات والأسرار وrunner.

يمثل ملف القفل طبقة مفيدة لضبط كود actions: فهو يجعل الإصدارات والتحديثات، بما فيها التبعيات الانتقالية، واضحة للمراجعة. ولضمان تغطية موثوقة، تحقّق أيضًا من سير العمل القابل لإعادة الاستخدام وactions المحلية، وأتمت تحديثها، ولا تفرض السياسة الإلزامية إلا بعد تجربة أولية.