gitlab

@semantic-release/gitlab

البرنامج المساعد للإصدار الدلالي لنشر إصدار GitLab.

خطوة	وصف
verifyConditions	التحقق من وجود وصلاحية المصادقة (المحددة عبر متغيرات البيئة).
publish	نشر إصدار GitLab.
success	أضف تعليقًا إلى كل مشكلة GitLab أو طلب دمج تم حله بواسطة الإصدار.
fail	افتح مشكلة GitLab أو قم بتحديثها بمعلومات حول الأخطاء التي تسببت في فشل الإصدار.

ثَبَّتَ

$ npm install @semantic-release/gitlab -D

الاستخدام

يمكن تكوين البرنامج المساعد في ملف تكوين الإصدار الدلالي :

{
  "branches" : [ " main " ],
  "plugins" : [
    " @semantic-release/commit-analyzer " ,
    " @semantic-release/release-notes-generator " ,
    [
      " @semantic-release/gitlab " ,
      {
        "gitlabUrl" : " https://custom.gitlab.com " ,
        "assets" : [
          { "path" : " dist/asset.min.css " , "label" : " CSS distribution " },
          { "path" : " dist/asset.min.js " , "label" : " JS distribution " , "target" : " generic_package " },
          { "path" : " dist/asset.min.js " , "label" : " v${nextRelease.version}.js " },
          { "url" : " https://gitlab.com/gitlab-org/gitlab/-/blob/master/README.md " }
        ]
      }
    ]
  ]
}

باستخدام هذا المثال، سيتم نشر إصدارات GitLab على مثيل https://custom.gitlab.com .

إعدادات

مصادقة جيتلاب

تكوين مصادقة GitLab مطلوب ويمكن ضبطه عبر متغيرات البيئة.

قم بإنشاء رمز وصول للمشروع أو رمز وصول جماعي أو رمز وصول شخصي مع دور المطور (أو أعلى) ونطاق api وجعله متاحًا في بيئة CI الخاصة بك عبر متغير البيئة GL_TOKEN . إذا كنت تستخدم GL_TOKEN كمصادقة لمستودع Git عن بعد، فيجب أن يكون له نطاق write_repository أيضًا.

ملاحظة : عند التشغيل باستخدام dryRun ، يلزم فقط نطاق read_repository .

متغيرات البيئة

عامل	وصف
GL_TOKEN أو GITLAB_TOKEN	مطلوب. الرمز المميز المستخدم للمصادقة مع GitLab.
GL_URL أو GITLAB_URL	نقطة نهاية GitLab.
GL_PREFIX أو GITLAB_PREFIX	بادئة GitLab API.
HTTP_PROXY أو HTTPS_PROXY	وكيل HTTP أو HTTPS للاستخدام.
NO_PROXY	الأنماط التي يجب تجاهل الوكيل لها. انظر التفاصيل أدناه.

تكوين الوكيل

يدعم البرنامج المساعد تمرير الطلبات من خلال خادم وكيل.

يمكنك تكوين خادم وكيل عبر متغير البيئة HTTPS_PROXY : HTTPS_PROXY=http://proxyurl.com:8080

إذا كان الخادم الوكيل الخاص بك يتطلب مصادقة، فقم بتضمين اسم المستخدم وكلمة المرور في عنوان URL: HTTPS_PROXY=http://user:[email protected]:8080

إذا تم عرض مثيل GitLab الخاص بك عبر HTTP العادي (غير مستحسن!) فاستخدم HTTP_PROXY بدلاً من ذلك.

إذا كنت بحاجة إلى تجاوز الوكيل لبعض المضيفين، فقم بتكوين متغير البيئة NO_PROXY : NO_PROXY=*.host.com, host.com

خيارات

خيار	وصف	تقصير
gitlabUrl	نقطة نهاية GitLab.	يوفر متغير البيئة GL_URL أو GITLAB_URL أو متغيرات البيئة CI إذا كان يعمل على GitLab CI/CD أو https://gitlab.com .
gitlabApiPathPrefix	بادئة GitLab API.	يوفر متغير البيئة GL_PREFIX أو GITLAB_PREFIX أو CI متغيرات البيئة في حالة التشغيل على GitLab CI/CD أو /api/v4 .
assets	مجموعة من الملفات للتحميل إلى الإصدار. انظر الأصول.	-
milestones	مجموعة من العناوين الرئيسية لربطها بالإصدار. راجع واجهة برمجة تطبيقات إصدار GitLab.	-
successComment	تم حل التعليق المراد إضافته إلى كل طلب إصدار ودمج بواسطة الإصدار. شاهد تعليق النجاح	؟ تم حل هذه المشكلة في الإصدار ${nextRelease.version}؟nnالإصدار متوفر في إصدار GitLab
successCommentCondition	استخدم هذا كشرط للتعليق على المشكلات أو طلبات الدمج. انظر حالة النجاح.	-
failComment	محتوى المشكلة التي تم إنشاؤها عند فشل الإصدار. انظر التعليق الفاشل.	رسالة ودية تحتوي على روابط لوثائق الإصدار الدلالي والدعم، مع قائمة بالأخطاء التي تسببت في فشل الإصدار.
failTitle	عنوان المشكلة التي تم إنشاؤها عند فشل الإصدار.	The automated release is failing
failCommentCondition	استخدم هذا كشرط للتعليق على أو إنشاء مشكلة في حالة الفشل. راجع FailCommentCondition.	-
labels	التسميات المراد إضافتها إلى المشكلة التي تم إنشاؤها عند فشل الإصدار. اضبط على false لعدم إضافة أي تصنيف. يجب أن تكون التسميات مفصولة بفواصل كما هو موضح في المستندات الرسمية، على سبيل المثال "semantic-release,bot" .	semantic-release
assignee	تم إنشاء المكلف بإضافته إلى المشكلة عند فشل الإصدار.	-

أصول

يمكن أن تكون كرة أرضية أو Array من الكرات الأرضية Object ذات الخصائص التالية:

ملكية	وصف	تقصير
path	مطلوب ، ما لم يتم تعيين url . كرة لتحديد الملفات المراد تحميلها. يدعم قوالب Lodash.	-
url	يوفر البديل لإعداد path إمكانية إضافة روابط للإصدارات، على سبيل المثال، عناوين URL لصور الحاوية. يدعم قوالب Lodash.	-
label	وصف موجز للملف المعروض في إصدار GitLab. يتم تجاهله إذا كان path يطابق أكثر من ملف واحد. يدعم قوالب Lodash.	اسم الملف مستخرج من path .
type	نوع الأصل المعروض في إصدار GitLab. يمكن أن يكون runbook package image other (راجع المستندات الرسمية حول أصول الإصدار). يدعم قوالب Lodash.	other
filepath	مسار ملف لإنشاء رابط ثابت يشير إلى الأصل (يتطلب GitLab 12.9+، راجع المستندات الرسمية حول الروابط الدائمة). يتم تجاهله إذا كان path يطابق أكثر من ملف واحد. يدعم قوالب Lodash.	-
target	التحكم في مكان تحميل الملف. يمكن ضبطه على project_upload لتخزين الملف كتحميل مشروع أو generic_package لتخزين الملف كحزمة عامة.	project_upload
status	يتم تطبيق هذا فقط إذا تم تعيين target على generic_package . حالة الحزمة العامة يمكن أن يكون default hidden (راجع المستندات الرسمية الخاصة بالحزم العامة).	default

يتم تجميع كل إدخال في Array assets بشكل فردي. يمكن أن تكون الكرة الأرضية عبارة عن String ( "dist/**/*.js" أو "dist/mylib.js" ) أو Array من String التي سيتم تجميعها معًا ( ["dist/**", "!**/*.css"] ).

إذا تم تكوين دليل، فسيتم تضمين كافة الملفات الموجودة ضمن هذا الدليل وأبناءه.

ملاحظة : إذا كان الملف يحتوي على تطابق في assets فسيتم تضمينه حتى لو كان لديه تطابق أيضًا في .gitignore .

أمثلة الأصول

'dist/*.js' : تضمين جميع ملفات js في دليل dist ، ولكن ليس في أدلةه الفرعية.

[['dist', '!**/*.css']] : يتضمن كافة الملفات الموجودة في دليل dist وأدلته الفرعية باستثناء ملفات css .

[{path: 'dist/MyLibrary.js', label: 'MyLibrary JS distribution'}, {path: 'dist/MyLibrary.css', label: 'MyLibrary CSS distribution'}] : تضمين dist/MyLibrary.js و dist/MyLibrary.css ، وقم بتسمية MyLibrary JS distribution MyLibrary CSS distribution في إصدار GitLab.

[['dist/**/*.{js,css}', '!**/*.min.*'], {path: 'build/MyLibrary.zip', label: 'MyLibrary'}] : تضمين جميع ملفات js و css الموجودة في دليل dist وأدلته الفرعية باستثناء الإصدار المصغر، بالإضافة إلى ملف build/MyLibrary.zip وتسميته MyLibrary في إصدار GitLab.

تعليق النجاح

يتم إنشاء رسالة تعليقات المشكلة باستخدام قالب Lodash. المتغيرات التالية متوفرة:

المعلمة	وصف
branch	Object يحمل name type channel range وخصائص prerelease للفرع الذي تم الإصدار منه.
lastRelease	Object يحتوي على version channel و gitTag و gitHead للإصدار الأخير.
nextRelease	Object يحتوي على version channel و gitTag و gitHead notes الإصدار الجاري تنفيذها.
commits	Array من Object الالتزام مع hash subject message body author .
releases	Array تحتوي على Object الإصدار لكل إصدار منشور، مع بيانات الإصدار الاختيارية مثل name وعنوان url .
issue	كائن مشكلة GitLab API الذي سيتم نشر التعليق عليه، أو false عند التعليق على طلبات الدمج.
mergeRequest	كائن طلب دمج واجهة برمجة تطبيقات GitLab الذي سيتم نشر التعليق عليه، أو false عند التعليق على المشكلات.

SuccessCommentCondition

يتم إنشاء شرط تعليق النجاح باستخدام قالب Lodash. المتغيرات التالية متوفرة:

المعلمة	وصف
branch	Object يحمل name type channel range وخصائص prerelease للفرع الذي تم الإصدار منه.
lastRelease	Object يحتوي على version channel و gitTag و gitHead للإصدار الأخير.
nextRelease	Object يحتوي على version channel و gitTag و gitHead notes الإصدار الجاري تنفيذها.
commits	Array من Object الالتزام مع hash subject message body author .
releases	Array تحتوي على Object الإصدار لكل إصدار منشور، مع بيانات الإصدار الاختيارية مثل name وعنوان url .
issue	كائن مشكلة GitLab API الذي سيتم نشر التعليق عليه.
mergeRequest	سيتم نشر كائن طلب دمج GitLab API إليه.

مثال على حالة النجاح

• لا تقم بإنشاء أي تعليقات على الإطلاق: اضبط على false أو قالب: "<% return false; %>"
• للتعليق فقط على المشكلات: "<% return issue %>"
• للتعليق على طلبات الدمج فقط: "<% return mergeRequest %>"
• يمكنك استخدام التصنيفات لتصفية المشكلات: "<% return issue.labels?.includes('semantic-release-relevant') %>"

تحقق من كائن طلب دمج GitLab API أو كائن مشكلة GitLab API بحثًا عن الخصائص التي يمكن استخدامها للمرشح

FailComment

يتم إنشاء الرسالة الخاصة بمحتوى المشكلة باستخدام قالب Lodash. المتغيرات التالية متوفرة:

المعلمة	وصف
branch	الفرع الذي فشل الإصدار منه.
errors	Array من SemanticReleaseError. يحتوي كل خطأ على خصائص message code pluginName details . يحتوي pluginName على اسم حزمة المكون الإضافي الذي تسبب في الخطأ. تحتوي details على معلومات حول الخطأ المنسق في تخفيض السعر.

مثال التعليق الفاشل

failComment This release from branch ${branch.name} had failed due to the following errors:n- ${errors.map(err => err.message).join('\n- ')} سيقوم بإنشاء الملف تعليق:

فشل هذا الإصدار من الفرع الرئيسي بسبب الأخطاء التالية:

• رسالة الخطأ 1
• رسالة الخطأ 2

FailCommentCondition

يتم إنشاء حالة التعليق الفاشل باستخدام قالب Lodash. المتغيرات التالية متوفرة:

المعلمة	وصف
branch	Object يحمل name type channel range وخصائص prerelease للفرع الذي تم الإصدار منه.
lastRelease	Object يحتوي على version channel و gitTag و gitHead للإصدار الأخير.
nextRelease	Object يحتوي على version channel و gitTag و gitHead notes الإصدار الجاري تنفيذها.
commits	Array من Object الالتزام مع hash subject message body author .
releases	Array تحتوي على Object الإصدار لكل إصدار منشور، مع بيانات الإصدار الاختيارية مثل name وعنوان url .
issue	كائن مشكلة GitLab API الذي سيتم نشر التعليق عليه - وهو متاح فقط في حالة وجود مشكلة مفتوحة.

مثال على فشل التعليق الشرطي

• لا تقم بإنشاء أي تعليقات على الإطلاق: اضبط على false أو قالب: "<% return false; %>"
• للتعليق فقط على الفرع الرئيسي: "<% return branch.name === 'main' %>"
• يمكنك استخدام التصنيفات لتصفية المشكلات، أي عدم التعليق إذا تم تصنيف المشكلة باستخدام wip : "<% return !issue.labels?.includes('wip') %>"

تحقق من كائن مشكلة GitLab API بحثًا عن الخصائص التي يمكن استخدامها للمرشح

التوافق

أحدث إصدار من هذا البرنامج الإضافي متوافق مع جميع إصدارات GitLab المدعومة حاليًا، وهو الإصدار الرئيسي الحالي والإصدارين الرئيسيين السابقين. هذا البرنامج المساعد غير مضمون للعمل مع الإصدارات غير المدعومة من GitLab.

كسر التغييرات في 14.0

إذا كنت تستخدم GitLab.com أو قمت بترقية مثيل GitLab المستضاف ذاتيًا إلى الإصدار 14.0، فيرجى استخدام الإصدار >=6.0.7 من هذا البرنامج الإضافي.

لماذا؟

في GitLab 14.0، تمت إزالة إنشاء إصدار باستخدام Tag API (انظر # 290311). تم تحديث هذا المكون الإضافي لاستخدام Releases API بدلاً من ذلك في رقم 184، المتوفر في الإصدار 6.0.7 وما بعده.