إعداد حساب الناشر

يُهيّئ دليل التشغيل هذا جانب الناشر من سطح الإصدار. لقصة التوزيع سجلّ واحد: حزمة npm ذات النطاق @ahmed-g-gad/apothem على npmjs.com، التي ينشرها سير العمل publish-npm.yml. يعمل سير العمل عند دفع الوسم v*.*.* بجانب release.yml ولا ينتظره (والتشغيل اليدوي مع المُدخَل tag هو البديل الاحتياطي). وموافقة بيئة release هي البوابة: يوافق عليها المُشغِّل بعد أن تصبح سِيَر عمل إصدار GitHub وPages وCI والمطابقة وأُطُر العمل خضراء. وكل مُنتَج آخر يُشحَن على صفحة إصدار GitHub نفسها ولا يحتاج إلى أي حساب ناشر خارجي.

خريطة الهوياتCopy Anchor Link

يُسمح لمالك GitHub بالتغيّر مستقبلًا. يقرأ منطق سير العمل والمُثبِّت github.repository أو github.repository_owner أو APOTHEM_GITHUB_REPO حيثما تسمح المنصّة بالحلّ الديناميكي. ويبقى معرِّف الحزمة في السجلّ مستقرًّا لأن المستخدمين يُثبّتون اسم الحزمة، لا اسم حساب المشرف.

npm (npmjs.com)Copy Anchor Link

1. سجِّل الدخول إلى https://www.npmjs.com/ بصفتك ahmed-g-gad.

2. فعِّل المصادقة الثنائية على الحساب.

3. تأكّد من اسم الحزمة ذات النطاق:

   Copy Text

   npm view @ahmed-g-gad/apothem name

   تعني الاستجابة 404 أن الحزمة ذات النطاق لم تُنشَر بعد. وأي استجابة أخرى عن الحزمة يجب أن تطابق هذا المستودع والحساب قبل النشر.

4. أنشئ الحزمة على npm إذا كانت الواجهة تتطلّب سجلّ حزمة أوليًا. أبقِ الاسم ذا نطاق: @ahmed-g-gad/apothem.

5. هيّئ Trusted Publishing للحزمة @ahmed-g-gad/apothem من GitHub Actions:

   • مالك GitHub: ahmed-g-gad
   • المستودع: apothem
   • اسم ملف سير العمل: publish-npm.yml
   • البيئة: release (قيمة environment: لمهمة النشر في publish-npm.yml؛ ويجب أن تتطابق القيمتان)
   • الإجراء المسموح به: npm publish.

6. في GitHub، تحقّق من أن البيئة release موجودة على ahmed-g-gad/apothem وأنها تتطلّب موافقة يدوية لعملية النشر.

7. اقصر سطح npm على حزمة سجلّ عامة واحدة: @ahmed-g-gad/apothem على npmjs.com.

8. وافِق على مهمة publish GitHub Release في تشغيل release.yml الذي يبدأه دفعُ الوسم. تنتظر المهمة موافقة بيئة release، ويحتاج الفحص أدناه إلى أن يكون ذلك التشغيل أخضر؛ ويُبيّن دليل تشغيل دورة الإصدار، §2.3، الطريقة. ثم تأكّد من جاهزية الإصدار:

   Copy Text

   bash scripts/release/check-release-ready.sh <release-tag>

   يحتاج الفحص إلى ضبط GH_TOKEN والملف sbom.cdx.json المنشور في dist/release-assets/. ويحدّد دليل تشغيل دورة الإصدار، §2.4، نطاق الرمز وأمر التنزيل.

9. وافِق على عملية النشر إلى بيئة release الخاصة بتشغيل Publish npm (publish-npm.yml) الذي يبدأه دفعُ الوسم. وإن لم يبدأ ذلك التشغيل، فشغِّل سير العمل يدويًا من تبويب GitHub Actions مع tag=<release-tag>.

10. تحقّق من الحزمة المنشورة فعليًا:

    Copy Text

    npm view @ahmed-g-gad/apothem version
    npx @ahmed-g-gad/apothem@<version> --version

لا يلزم أي سرّ من نوع NPM_TOKEN أو اسم مستخدم أو كلمة مرور. ينشر سير العمل عبر npm Trusted Publishing (OIDC) بنسخة Node وبالحدّ الأدنى لدعم OIDC في npm CLI، المُثبَّتين داخل .github/workflows/publish-npm.yml. ويُشغِّل npm publish --provenance --access public مقابل npmjs.com، فيكون بيان المنشأ الخاص بـ Sigstore صريحًا؛ كما يُصدِر npm المنشأ افتراضيًا للحزم العامة المنشورة من سير عمل عام في GitHub Actions. يعني الخطأ 404 من السجلّ أثناء PUT أن الناشر الموثوق على جانب npm، أو نطاق الحزمة، أو تفويض الحساب لم يُضبَط بعد؛ أصلِح إعدادات الحزمة على npm قبل إعادة محاولة سير العمل.

بمجرد نجاح نشر موثوق، أغلِق مسار الرموز المميّزة نهائيًا: في Settings → Publishing access الخاصة بالحزمة على npmjs.com، اختر Require two-factor authentication and disallow tokens، واحذف أي سرّ لرمز npm مميّز متبقٍّ في المستودع. لم يعد سير العمل يقرأ أي رمز.

المراجع: الناشرون الموثوقون في npm، والمنشأ في npm، والنطاقات في npm.

المتطلّبات المسبقة للإصدار على جانب GitHubCopy Anchor Link

أسطح الإصدار المتبقّية أصلية في GitHub وتُصادِق باستخدام GITHUB_TOKEN ذي نطاق المستودع؛ ولا يدخل فيها أي حساب خارجي.

1. إصدار GitHub. يعمل .github/workflows/release.yml على وسم النسخة ولا يحتاج إلا إلى صلاحية contents: write المحلّية لمهمّته. تأكّد من وجود ملف سير العمل على main قبل وضع الوسم.

2. النطاق المخصّص لـ Pages. يُنشَر موقع الوثائق عبر publish-static-site.yml إلى النطاق المخصّص apothem.ahmedgad.com. يُؤسِّس دليل تشغيل تفعيل Pages النطاقَ وDNS وفرض HTTPS؛ تحقّق:

   Copy Text

   gh api repos/ahmed-g-gad/apothem/pages --jq '.cname, .https_enforced'
   curl -sSI https://apothem.ahmedgad.com/ | head -n 1

3. مُثبِّتات السكربت. يُقدَّم install.sh وinstall.ps1 من موقع Pages (https://apothem.ahmedgad.com/install.sh وhttps://apothem.ahmedgad.com/install.ps1). وتنشرهما عملية النشر نفسها إلى Pages؛ ولا يلزم حساب أو رمز مميّز منفصل.

مصفوفة التحقّقCopy Anchor Link

بعد الإعداد، يستجيب كل سطح ناشر لفحصه المرجعي: