نشر إجراء GitHub مخصص

  • 6 دقائق

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

اختر موقعًا للإجراء لديك

رسم تخطيطي يعرض خياري الرؤية لإجراء: عام أو خاص.

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

‏‏عامة

يمكن أن تستخدم مهام سير العمل في أي مستودع الإجراءات العامة. إذا كنت تقوم بتطوير إجراء بهدف جعله مصدر مفتوح أو جعله متاحا للجمهور من خلال GitHub Marketplace، نوصي (وفي معظم الحالات يكون مطلوبا) بأن يكون للإجراء مستودعه الخاص بدلا من تجميعه مع التعليمات البرمجية للتطبيقات الأخرى. يسمح لك هذا بإصدار الإجراء وتعقبه وإصداره تماما مثل أي جزء آخر من البرامج. وهذا يجعل من السهل على مجتمع GitHub اكتشاف الإجراء، وكذلك تضييق نطاق قاعدة التعليمات البرمجية للمطورين الذين يصلحون المشكلات ويوسعون إصدار الإجراء، ويفصل إصدار الإجراء عن إصدار تعليمة التطبيق البرمجية الأخرى.

خاصة

عندما يكون الإجراء في مستودع خاص، يمكن فقط لسير العمل في نفس المستودع استخدام الإجراء. مع الإجراءات الخاصة، يمكنك تخزين ملفات الإجراء في أي موقع في المستودع لديك. إذا كنت تخطط لدمج الإجراء وسير العمل ورمز التطبيق في مستودع واحد، نوصي بتخزين الإجراء في .github الدليل. على سبيل المثال، .github/actions/action-a و .github/actions/action-b.

توثيق الإجراء لديك

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

غالبًا ما يكون الملف README.md هو المكان الأول الذي سينظر إليه المطورون لمعرفة كيفية عمل الإجراء. هذا هو مكان رائع لتضمين جميع المعلومات الهامة للإجراء. فيما يلي قائمة غير شاملة بالأشياء التي يجب تضمينها:

  • وصف مفصل لما يقوم به الإجراء.
  • وسيطات الإدخال والإخراج المطلوبة.
  • وسيطات الإدخال والإخراج الاختيارية.
  • البيانات السرية التي يستخدمها الإجراء.
  • متغيرات البيئة التي يستخدمها الإجراء.
  • مثال على كيفية استخدام الإجراء الخاص بك في سير عمل.

كقاعدة عامة، يجب أن يشمل الملف README.md كل ما يجب أن يعرفه المستخدم لاستخدام الإجراء. إذا كنت تعتقد أنها قد تكون معلومات مفيدة، فبادر بتضمينها في README.md.

إصدار الإجراء وطرحه

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

الممارسات الجيدة لإدارة الإصدار والطرح

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

علامات

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

  • إنشاء إصدار والتحقق من صحته على فرع إصدار (مثل release/v1) قبل إنشاء علامة الإصدار (على سبيل المثال v1.0.2).
  • استخدم إصدارًا دلاليًا.
  • انقل علامة الإصدار الرئيسية (مثل v1، v2) للإشارة إلى مرجع Git للإصدار الحالي.
  • أدخل علامة إصدار رئيسية جديدة (v2) للتغييرات التي ستقطع مهام سير العمل الحالية.
  • إصدار الإصدارات الرئيسية مع علامة بيتا للإشارة إلى حالتها؛ على سبيل المثال، v2-beta. يمكنك إزالة العلامة -beta عندما يكون الإصدار جاهزًا.

فيما يلي بعض الأمثلة على كل خيار.

steps:
    - uses: actions/javascript-action@v1
    - uses: actions/javascript-action@v1.0.1
    - uses: actions/javascript-action@v1-beta

استخدام SHA للالتزام

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

steps:
    - uses: actions/javascript-action@2522385f6f7ba04fe7327647b213799853a8f55c

توزيع إجراء إلى GitHub Marketplace

العرض الذي يقول GitHub Marketplace، أدوات للبناء على سير العمل وتحسينه.

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

فيما يلي متطلبات نشر إجراء إلى GitHub Marketplace. وهي تنطبق على كل من الإجراءات المستندة إلى حاوية Docker والإجراءات المستندة إلى JavaScript:

  • يجب أن يكون الإجراء في مستودع عام.
  • يجب أن يحتوي كل مستودع على إجراء واحد.
  • يجب أن يكون ملف بيانات تعريف الإجراء (action.yml أو action.yaml) في الدليل الجذر للمستودع.
  • يجب أن يكون name المتوفر في ملف بيانات التعريف للإجراء فريدًا على GitHub Marketplace.
    • لا يمكن أن يتطابق الاسم مع مستخدم أو مؤسسة على GitHub، إلا إذا كان المستخدم أو مالك المؤسسة ينشر الإجراء. على سبيل المثال، يمكن لمؤسسة GitHub فقط نشر إجراء باسم github.
    • name لا يمكن أن يتطابق مع فئة GitHub Marketplace موجودة.
    • لا يمكن أن يتطابق name مع ميزة GitHub موجودة.

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