المزامنة مع GitLab

طُوّرت هذه الميزة بواسطة ayaka-notes/ayakaleaf-pro. وهي متاحة بدءًا من الإصدار v6.4.0 وما بعده. لا تزال في مرحلة تجريبية (beta). نحتاج إلى ملاحظاتك إذا واجهت أي مشكلة.

تعمل المزامنة مع GitLab بطريقة مماثلة لـ المزامنة مع GitHub: يربط المستخدمون حساباتهم على GitLab، ويصدّرون المشاريع إلى مشاريع GitLab جديدة، ويستوردون مستودعات GitLab، ويزامنون التغييرات في كلا الاتجاهين. وهي تعمل مع GitLab.com ومع نسخ GitLab المُدارة ذاتيًا بالإصدار 15.10 أو أحدث (الإصداران Community وEnterprise).

​

إعداد المزامنة مع GitLab

يجب عليك تفعيل git-bridge أولًا قبل استخدام المزامنة مع GitLab.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

أنشئ تطبيق OAuth على نسخة GitLab الخاصة بك، ضمن User settings → Applications (أو Admin area → Applications لتطبيق على مستوى النسخة بأكملها):

• Redirect URI: ${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
• Confidential: مُحدَّد
• Scopes: api

انسخ Application ID وSecret، ثم أضف الإعدادات التالية إلى ملفات متغيرات البيئة الخاصة بـ overleaf.

config/variables.env

# used to encrypt the user's GitLab access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITLAB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# GitLab Sync Settings
GITLAB_SYNC_ENABLED=true
GITLAB_SYNC_CLIENT_ID=
GITLAB_SYNC_CLIENT_SECRET=

# Web address of your GitLab, defaults to https://gitlab.com
# GITLAB_SYNC_URL=https://gitlab.example.com

# OAuth callback is: ${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
# (Optional) GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808

قبل تكوين عنوان إعادة التوجيه (redirect URI) الخاص بـ GitLab OAuth، تأكد من ضبط OVERLEAF_SITE_URL بشكل صحيح.

تنتهي صلاحية رموز الوصول (access tokens) في GitLab بعد ساعتين. يجدّدها Overleaf باستخدام رمز التحديث (refresh token) الذي يصدره GitLab معها، لذا يبقى المستخدمون مرتبطين إلى أن يلغوا الربط أو يُبطلوا التطبيق في GitLab.

​

GitLab المُدار ذاتيًا

اضبط GITLAB_SYNC_URL على عنوان الويب الخاص بنسختك، أي العنوان الذي تفتح به المشاريع في المتصفح. ويُشتق منه عنوان REST API:

المتغير	القيمة الافتراضية
GITLAB_SYNC_URL	https://gitlab.com
GITLAB_SYNC_API_URL	${GITLAB_SYNC_URL}/api/v4

لا تضبط GITLAB_SYNC_API_URL إلا إذا كانت نسختك تقدّم الواجهة البرمجية (API) في مكان آخر، على سبيل المثال خلف بوابة API.

• أنشئ تطبيق OAuth على النسخة التي ضبطتها في GITLAB_SYNC_URL، فالتطبيق المُنشأ على gitlab.com لا يعمل على نسخة مُدارة ذاتيًا.
• GITLAB_SYNC_URL هو عنوان الويب فقط. لا تُضِف /api/v4 أو مسار مجموعة (group).

إذا كانت نسختك تستخدم شهادة صادرة عن مرجع مصادقة خاص (private CA)، فاربط شهادة CA داخل الحاوية واجعل NODE_EXTRA_CA_CERTS يشير إليها، مثل NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitlab-ca.pem.

تنتمي الحسابات والمشاريع المرتبطة إلى النسخة التي رُبطت بها. قبل تبديل GITLAB_SYNC_URL إلى نسخة أخرى، اطلب من المستخدمين إلغاء ربط حساباتهم ومشاريعهم على GitLab.

إذا كنت موجودًا في منطقة ذات وصول مقيّد إلى الشبكة، فقد تحتاج إلى تكوين وكيل (proxy) للوصول إلى GitLab. اضبط متغير البيئة التالي: GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808. يجب أن يكون وكيلًا أماميًا قياسيًا من نوع HTTP/HTTPS، ويجب ألا يستخدم 127.0.0.1.

​

من يمكنه الربط والمزامنة

كما هو الحال في Overleaf Cloud، لا يمكن إلا لمالك المشروع ربط المشروع بمستودع GitLab. وبمجرد ربطه، يمكن لكل متعاون لديه صلاحية التحرير مزامنته.

الإجراء	من يمكنه تنفيذه
تصدير مشروع إلى مستودع GitLab جديد	مالك المشروع
استيراد مستودع GitLab إلى مشروع جديد	أي مستخدم، ويصبح مالك المشروع الجديد
السحب (pull) والدفع (push) والدمج (merge) لمشروع مرتبط	المالك والمتعاونون الذين لديهم صلاحية التحرير
إلغاء ربط مشروع بمستودعه	مالك المشروع

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

​

كيف تعمل المزامنة مع GitLab

• الصلاحيات: يجب أن يكون مسموحًا للمستخدمين بالدفع إلى الفرع الافتراضي للمشروع المرتبط. عندما يكون الفرع الافتراضي محميًا ولا يُسمح للمستخدم بالدفع إليه، يطلب منه Overleaf التواصل مع مالك المشروع، كما هو الحال مع مستودع فقد الوصول إليه.
• الدمج: عندما يتغيّر المشروع في كلٍّ من Overleaf وGitLab، يُودِع Overleaf تغييراته في فرع مؤقت باسم overleaf-YYYY-MM-DD-HHMMSS ويدمجه عبر طلب دمج (merge request)، لأن GitLab لا يوفّر واجهة برمجية لدمج الفروع دون طلب دمج. بعد الدمج، يحذف Overleaf الفرع المؤقت وطلب الدمج. ولا يُسمح بحذف طلبات الدمج في GitLab إلا للمسؤولين ومالكي المشاريع، لذا يبقى طلب الدمج المُدمَج في المشروع بالنسبة إلى المستخدمين الآخرين.
• قواعد الدمج: لا يتجاوز Overleaf أبدًا قواعد الدمج الخاصة بالمشروع. عندما يحتوي طلب الدمج على تعارض، أو يتطلب موافقة أو نجاح خط أنابيب (pipeline)، فإنه يبقى مفتوحًا ويطلب Overleaf من المستخدم دمجه في GitLab، ثم متابعة المزامنة.
• خطوط الأنابيب: تُطلق الإيداعات (commits) القادمة من Overleaf خطوط الأنابيب مثل أي إيداع آخر. إذا كان مشروعك يشغّل خطوط أنابيب لطلبات الدمج ويشترط نجاحها، فإن عمليات الدمج القادمة من Overleaf تنتظرها، كما هو موضح أعلاه.

​

أسئلة وأجوبة (Q&A)

هل يمكنني إجراء دفع قسري (force push) إلى الفرع الافتراضي؟

الإجابة: يُرجى إبقاء الدفع القسري إلى الفرع الافتراضي معطّلًا. وهذا هو الإعداد الافتراضي في GitLab: يكون الفرع الافتراضي للمشروع الجديد محميًا ولا يمكن لأحد إجراء دفع قسري إليه. يمكن لـ Overleaf تولّي فرع أُعيدت كتابته، لكن المزامنة مع GitLab مصمَّمة لفرع افتراضي لا ينمو سجلّه إلا بالإضافة.

هل يمكنني إعادة تسمية الفرع الافتراضي لمشروع مرتبط؟

الإجابة: لا. يواصل Overleaf المزامنة مع الفرع الذي رُبط به المشروع، لذا تفشل عمليات المزامنة بمجرد إعادة تسمية ذلك الفرع أو حذفه. للمزامنة مع فرع آخر، ألغِ ربط المشروع، ثم استورد المستودع إلى مشروع جديد، والذي سيستخدم الفرع الافتراضي الحالي.