التكامل مع Git

أتِح للمستخدمين استنساخ مشاريعهم وسحبها ودفعها باستخدام Git عبر git-bridge.

التكامل مع Git متاح حاليًا في ayaka-notes/overleaf.

طُوّرت هذه الميزة في البداية من قِبل ayaka-notes/ayakaleaf-pro.

1. تفعيل git-bridge (لمستخدمي Toolkit فقط)

   إذا كنت تستخدم Toolkit، فعّل git-bridge عبر تعيين ما يلي في الملف config/overleaf.rc:

   config/overleaf.rc

   GIT_BRIDGE_ENABLED=true
   

   يتجاهله Toolkit ما لم يُضبط SERVER_PRO=true أيضًا. لا حاجة إلى أي شيء آخر: إذ يضبط Toolkit المتغيرات GIT_BRIDGE_HOST وGIT_BRIDGE_PORT وV1_HISTORY_URL للحاوية sharelatex بنفسه، لذا تخطَّ خطوتَي Docker Compose أدناه. شغّل bin/up لإعادة إنشاء الحاويات.

2. إضافة حاوية git-bridge (لمستخدمي Docker-compose فقط)

   بالنسبة للمستخدمين الذين يشغّلون ملف docker-compose.yml مخصصًا، أضف إعداد الحاوية التالي إلى ملف compose الخاص بك:

   docker-compose.yml (git-bridge service)

   git-bridge:
       restart: always
       image: ghcr.io/ayaka-notes/overleaf-pro/git-bridge:6.3.2 # tag should match the `sharelatex` container tag
       volumes:
           - ~/git_bridge_data:/data/git-bridge
       container_name: git-bridge
       expose:
           - "8000"
       environment:
           GIT_BRIDGE_API_BASE_URL: "http://sharelatex:3000/api/v0/" 
           GIT_BRIDGE_OAUTH2_SERVER: "http://sharelatex"
           GIT_BRIDGE_POSTBACK_BASE_URL: "http://git-bridge:8000"
           GIT_BRIDGE_ROOT_DIR: "/data/git-bridge"
       user: root
       command: ["/server-pro-start.sh"]
   

   استخدم الوسم نفسه المستخدم لصورة sharelatex. يُعد خادم MCP (الإصدار v6.3.1 وما بعده) جزءًا من صورة sharelatex ويُفعَّل مع التكامل مع Git، لذا لا يحتاج إلى حاوية إضافية.

3. تحديث إعداد حاوية sharelatex

   ستحتاج أيضًا إلى ربط الحاوية git-bridge في الحاوية sharelatex وتعريف متغيرات البيئة التالية، ويُرجى الانتباه إلى V1_HISTORY_URL:

   docker-compose.yml (sharelatex service)

   sharelatex:
       links:
           - git-bridge
       environment:
            GIT_BRIDGE_ENABLED: true
            GIT_BRIDGE_HOST: "git-bridge"
            GIT_BRIDGE_PORT: "8000"
            # We use v1 now, if you used to set V1_HISTORY_URL, please update now
            V1_HISTORY_URL: "http://sharelatex:3100/api"
   
4. المصادقة

   عند مصادقة عميل git، يحتاج المستخدمون إلى رمز وصول شخصي (Personal Access Token). ويمكن للمستخدمين إدارة رموز الوصول الشخصية عبر واجهة التطبيق (راجع التوثيق):

   

   رمز الوصول الشخصي للتكامل مع Git

5. المراقبة واعتبارات الموارد

   نوصي بمراقبة موارد الجهاز المضيف بعد تفعيل git-bridge. وستعتمد زيادة الحمل على:

   • عدد المستخدمين الذين يستخدمون الميزة
   • أنواع المشاريع المستضافة في نسختك (المشاريع الأكبر تستهلك عمومًا موارد أكثر)

​

نقل المشاريع إلى S3

يخزّن التكامل مع Git مستودع git كاملًا على القرص لكل مشروع يستنسخه مستخدم. إذا كانت مساحة القرص لديك محدودة، يمكنك تفعيل مهمة تبديل (swap job) تنقل المستودعات الأقل استخدامًا إلى AWS S3. وإذا احتيج إلى مستودع تم نقله مرة أخرى، فسيُعاد إلى القرص. تتحكم متغيرات البيئة التالية في مهمة التبديل:

الاسم	الوصف
GIT_BRIDGE_SWAPSTORE_TYPE	عيّن هذه القيمة إلى “s3” لتفعيل مهمة التبديل.
GIT_BRIDGE_SWAPSTORE_AWS_ACCESS_KEY	مفتاح الوصول إلى AWS الخاص بك
GIT_BRIDGE_SWAPSTORE_AWS_SECRET	المفتاح السري لـ AWS الخاص بك
GIT_BRIDGE_SWAPSTORE_S3_BUCKET_NAME	ستحتوي هذه الحاوية (bucket) على مستودعات git المضغوطة
GIT_BRIDGE_SWAPSTORE_AWS_REGION	منطقة الحاوية (bucket)
GIT_BRIDGE_SWAPJOB_MIN_PROJECTS	الحد الأدنى لعدد المشاريع التي يجب الاحتفاظ بها على القرص. - القيمة الافتراضية: 50
GIT_BRIDGE_SWAPJOB_LOW_GIB	الحد الأدنى للتبديل. ستنقل مهمة التبديل المشاريع حتى يصبح استخدام القرص أقل من هذه القيمة. - القيمة الافتراضية: 128 GB
GIT_BRIDGE_SWAPJOB_HIGH_GIB	الحد الأعلى للتبديل. ستبدأ مهمة التبديل بالعمل عندما يصل استخدام القرص إلى هذه القيمة. - القيمة الافتراضية: 256 GB
GIT_BRIDGE_SWAPJOB_INTERVAL_MILLIS	الفترة الزمنية بين فحص استخدام القرص وتشغيل مهمة التبديل. - القيمة الافتراضية: 3600000 ms = ساعة واحدة

​

أسئلة وأجوبة

إذا شاركت مشروعي مع شخص آخر، كيف يعمل نموذج الأذونات في Git Bridge؟

يمكن للمستخدمين الذين لديهم صلاحية القراءة فقط استنساخ هذا المشروع فقط؛ أما المستخدمون الذين لديهم صلاحية القراءة والكتابة فيمكنهم استنساخ المشاريع ودفع التغييرات إليها (push). ملاحظة: يجب أن يكون المستخدمون مسجّلين الدخول للانضمام إلى هذا المشروع.

كيف أستنسخ مشروعًا، وما اسم المستخدم وكلمة المرور اللذان أستخدمهما؟

في المحرر، افتح Integrations في الشريط الجانبي الأيسر وانقر على Git integration. سيعرض لك أمر الاستنساخ بالصيغة التالية:

git clone https://<your-overleaf>/git/<project_id>

عندما يطلب Git بيانات الاعتماد، أدخل git كاسم مستخدم ورمز وصول شخصي (Personal Access Token) ككلمة مرور. أنشئ الرمز من Account Settings؛ وهو صالح لمدة عام واحد. لا تعمل كلمة مرور حسابك.

لا تُزامَن التغييرات تلقائيًا: استخدم git pull لجلب التغييرات التي أُجريت في المحرر وgit push لإرسال تغييراتك. يُقدَّم المسار /git من خلال الحاوية sharelatex، لذا لا يحتاج الوكيل العكسي الموجود أمامها إلى أي قاعدة إضافية.

يفشل git push مع HTTP 413 أو curl 55 Broken pipe

حجم الدفع أكبر من حد حجم الرفع، الذي يُضبط عبر MAX_UPLOAD_SIZE (بالميغابايت، 50 افتراضيًا) وينطبق أيضًا على عمليات الدفع. ارفعه في config/variables.env، على سبيل المثال MAX_UPLOAD_SIZE=200، ثم شغّل bin/up -d. إذا كنت تستخدم وكيل TLS أو وكيلًا عكسيًا خاصًا بك، فارفع أيضًا قيمة client_max_body_size الخاصة به (50M في ملف config/nginx/nginx.conf الخاص بـ Toolkit).

يرفض git-bridge أيضًا الملفات التي يزيد حجمها على 50 ميغابايت والمشاريع التي تحتوي على أكثر من 2,000 ملف. تُضبط هذه الحدود عبر GIT_BRIDGE_REPOSTORE_MAX_FILE_SIZE (بالبايت) وGIT_BRIDGE_REPOSTORE_MAX_FILE_NUM في config/variables.env.

يُظهر سجل git-bridge الرسالة Failed to fetch log level

هذا التحذير غير ضار، وتستمر عمليات clone وpull وpush في العمل. في الإصدارات 6.2.x، يطلب git-bridge مستوى السجل من خادم البيانات الوصفية لـ Google Cloud (metadata.google.internal) مرة كل دقيقة، وهو ما لا ينجح إلا على Google Cloud. وفي غير ذلك يفشل الطلب، فيسجّل git-bridge الخطأ (مثل null أو حالة HTTP) ويحتفظ بالمستوى المحدد في GIT_BRIDGE_LOG_LEVEL. بدءًا من 6.3.0 يكون هذا الفحص معطّلًا، كما أن الترقية تحدّث أيضًا صورة git-bridge، التي يتبع إصدارها إصدار الصورة الرئيسية.

هل أحتاج إلى خدمة track-changes أو إلى OVERLEAF_IS_SERVER_PRO=true من أجل Git والسجل الكامل للمشروع؟

الإجابة: لا. لا يتضمن Ayakaleaf Pro خدمة track-changes. يُحفَظ سجل المشروع بواسطة الخدمتين project-history وhistory-v1، اللتين تعملان دائمًا داخل الحاوية sharelatex. يقرأ git-bridge السجل من history-v1 عبر V1_HISTORY_URL (http://sharelatex:3100/api)، الذي يضبطه Toolkit. لا تضبط OVERLEAF_IS_SERVER_PRO: إذ لا تعتمد عليه أي ميزة، وكل ما يفعله هو تحويل عمليات ترحيل قاعدة البيانات التي تُشغَّل عند بدء التشغيل إلى مجموعة Server Pro.