ربط مستودع للتأليف ثنائي الاتجاه عبر Git

يستطيع Nibleaf استيراد مستودع بالطريقة المعتادة، أو ربط مستودع GitHub للتأليف ثنائي الاتجاه. في الوضع ثنائي الاتجاه، تُحفَظ تعديلات المتصفح في فرع مخصص، ويُنشأ طلب سحب في حالة مسودة أو يُحدَّث، وتُجرى تسوية التعارضات مع تغييرات المنبع، ويحصل كل طلب سحب على معاينة ثابتة غير قابلة للتغيير تحمل التوجيه noindex.

إعداد نسخة Nibleaf

طبّق ترحيل قاعدة البيانات قبل تفعيل واجهة المستخدم:

pnpm db:deploy

اضبط سرَّين مستقلين في خدمتي API والعامل:

# Exactly 32 bytes, base64 encoded. Encrypts provider credentials and webhook secrets.
openssl rand -base64 32

# At least 32 characters. Authenticates opaque worker callbacks to the API.
openssl rand -hex 32

عيّن الناتجين في GIT_CREDENTIAL_ENCRYPTION_KEY وGIT_WORKER_SECRET. القيمة الافتراضية لـGIT_CONCURRENCY هي 2. إذا كان WORKER_QUEUES قائمة سماح، فأضف إليها git. أعد تشغيل API والعامل بعد تغيير هذه القيم.

لا تبدّل GIT_CREDENTIAL_ENCRYPTION_KEY في موضعه: لا يمكن فك النصوص المشفّرة الحالية بمفتاح جديد. لتبديله، افصل أولًا كل اتصال Git أو أعد تشفيره ضمن ترحيل مضبوط، ثم انشر المفتاح الجديد وأعد ربط بيانات الاعتماد. أما تبديل GIT_WORKER_SECRET فلا يتطلب إلا نشر القيمة الجديدة نفسها في API والعامل معًا.

إعداد بيانات اعتماد GitHub والمستودع

أنشئ رمز وصول شخصيًا دقيق الصلاحيات أو بيانات اعتماد تثبيت مقيَّدة بالمستودع المتصل. لا تمنح إلا:

• Metadata: read
• Contents: read and write
• Pull requests: read and write

لا حاجة إلى أي صلاحيات تخص Actions أو الإدارة أو المشكلات أو المؤسسة أو المستخدم. الصق الرمز مرة واحدة في إعدادات الموقع ← Git. يتحقق Nibleaf من صلاحية الكتابة، ويشفّر الرمز باستخدام AES-256-GCM، ويخزّن بصمة غير سرية للمشغّلين، ولا يعيد الرمز أو يسجّله مطلقًا.

اختر فرعًا أساسيًا (عادةً main)، وفرع تأليف مخصصًا ومختلفًا (مثل nibleaf/docs)، ومسار التوثيق نسبةً إلى جذر المستودع، وفرع Nibleaf/اللغة المراد ربطهما. لا ينفّذ Nibleaf دفعًا قسريًا مطلقًا. تستخدم تحديثات الفروع دلالات المقارنة ثم التبديل وتتوقف إذا تغيّر المرجع البعيد أثناء الدفع.

إعداد Webhook

في مستودع GitHub، أضف عنوان URL للحمولة الذي يعرضه Nibleaf:

https://YOUR_NIBLEAF_ORIGIN/api/public/git/webhook/PROJECT_ID

استخدم application/json، والصق السر الذي أنشأته أو بدّلته في لوحة Git، وفعّل التحقق من SSL، واشترك في Pushes وPull requests.

يُتحقق من عمليات التسليم الواردة من GitHub باستخدام X-Hub-Signature-256 مقابل بايتات الطلب الخام نفسها تمامًا. يُخزّن X-GitHub-Delivery مع تجزئة للحمولة، لذلك يُقرّ بعمليات التسليم المعادة بطريقة متكافئة النتائج، بينما يُرفض استخدام معرّف تسليم سابق مع بايتات مختلفة. لا توضع أجسام Webhook ولا بيانات الاعتماد في Redis؛ إذ لا تحتوي المهام إلا على معرّف عملية مبهم.

تظل اتصالات GitHub/GitLab العامة الحالية أحادية الاتجاه قابلة للقراءة، وتحتفظ بسلوك Webhook القديم إلى أن يضيف مسؤول اتصال GitHub مشفّرًا وثنائي الاتجاه.

سلوك الإيداع وطلب السحب والمعاينة

يجوز للمؤلفين الذين لديهم دور member في الموقع أو دور أعلى إدراج عمليات الدفع في قائمة الانتظار، وسحب تغييرات المنبع، وتسوية التعارضات. أما بيانات اعتماد المستودع وتبديل Webhook وتغييرات الاتصال وفصله فتتطلب دور admin أو owner.

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

ينشئ موصّل GitHub طلب سحب واحدًا في حالة مسودة أو يحدّثه لزوج فرع الرأس/الفرع الأساسي المضبوط. تعرض واجهة المستخدم الملفات المتغيرة، وحالة العملية الدائمة، وحالة طلب السحب، ودورة حياة المعاينة (PENDING أو BUILDING أو READY أو FAILED أو SUPERSEDED). معاينات READY لقطات ثابتة غير قابلة للتغيير على رابط يصعب تخمينه، وترسل noindex, nofollow؛ ويؤدي إغلاق طلب السحب إلى استبدال معاينته النشطة.

جولة مرئية

تشرح لوحة Git صلاحيات GitHub ذات أقل قدر من الامتياز، وتُبقي الفرع الأساسي وفرع التأليف المخصص واضحين عندما يربط مسؤول مستودعًا.

بعد الدفع، تعرض اللوحة نفسها العملية الدائمة، ونَسب الإيداع إلى مؤلفه، والملفات المتغيرة، وطلب السحب في حالة مسودة، ودورة حياة المعاينة.

تعرض المعاينة العامة اللقطة الثابتة غير القابلة للتغيير لطلب السحب بصورة مستقلة عن مساحة عمل التأليف.

دلالات التعارض

يخزّن كل ملف متتبَّع آخر أساس مشترك. قبل تغيير أي من الجانبين، يقارن Nibleaf بين:

• base: آخر إصدار قبله كلا النظامين؛
• ours: التسلسل الحالي لصفحة Nibleaf؛
• theirs: الملف الحالي من Git.

إذا تغيّر جانب واحد فقط، يُحفظ ذلك التغيير تلقائيًا. وتتقارب التعديلات المتطابقة. تُعامل إضافة الملفات وحذفها بوصفهما حالتين مستقلتين، لا كسلاسل فارغة. إذا تغيّر الجانبان بصورة مختلفة، تنتقل العملية إلى CONFLICT ولا يُستبدل أي مرجع في المستودع أو أي صفحة في Nibleaf.

تعرض واجهة المستخدم محتوى base/ours/theirs كاملًا لكل ملف متعارض. ويجب أن يختار المؤلف صراحةً محتوى Nibleaf أو Git أو محتوى مخصصًا أو حذفًا مخصصًا. بعد تسوية جميع الملفات، تُعاد محاولة العملية الدائمة نفسها. ويُجرى فحص ثانٍ للمرجع البعيد مباشرةً قبل التحديث، كي لا تضيع بصمت التغييرات التي تصل أثناء تسوية التعارضات.

يعرض التسجيل القصير التالي حلًا صريحًا لكل ملف وعودة العملية إلى قائمة الانتظار الدائمة. لا يتغير أي جانب قبل أن يختار المؤلف حلًا.

التعافي التشغيلي

• بقاء الحالة QUEUED طويلًا: تحقق من Redis، وتأكد من أن العامل يشغّل قائمة انتظار git، وأن GIT_WORKER_SECRET متطابق في API والعامل. إعادة إدراج العملية نفسها في قائمة الانتظار آمنة.
• الحالة FAILED مع 401/403: بدّل بيانات اعتماد المستودع مع الالتزام بالصلاحيات الموثقة ذات أقل قدر من الامتياز. رسائل خطأ المزوّد محدودة ولا تحتوي على أسرار.
• تغيّر الفرع البعيد: اسحب تغييرات المنبع، وسوِّ أي تعارضات، ثم أرسل عملية دفع جديدة متكافئة النتائج. لا ينفّذ Nibleaf دفعًا قسريًا لتجاوز هذا الخطأ مطلقًا.
• فشل المعاينة: افحص خطأ العملية/المعاينة في لوحة Git، وأصلح مشكلة المحتوى أو البنية التحتية، ثم حدّث طلب السحب في حالة مسودة. يمنع مفتاح تفرّد SHA للمصدر إنشاء نسخ مكررة.
• إعادات محاولة Webhook: قد يعيد GitHub تسليم المعرّف نفسه بأمان. إذا لم يكن Redis متاحًا، تضع إعادة التسليم مفتاح تكافؤ النتائج نفسه في قائمة الانتظار.
• فقدان سر Webhook: بدّله في Nibleaf، وحدّث Webhook في GitHub فورًا، واستخدم إجراء إعادة التسليم في GitHub للأحداث الفائتة.
• فقدان مفتاح التشفير: صُممت بيانات الاعتماد المشفّرة بحيث يتعذر استعادتها. عيّن مفتاحًا جديدًا وأعد ربط كل مستودع متأثر؛ وينبغي أيضًا إبطال رموز المزوّد واستبدالها.

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