المزامنة مع Gitea

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

تعمل المزامنة مع Gitea بطريقة مماثلة لـ المزامنة مع GitHub والمزامنة مع GitLab: يربط المستخدمون حساباتهم على Gitea، ويصدّرون المشاريع إلى مستودعات Gitea جديدة، ويستوردون مستودعات Gitea، ويزامنون التغييرات في كلا الاتجاهين. وهي تعمل مع Gitea بالإصدار 1.23 أو أحدث، على gitea.com أو على نسختك الخاصة.

​

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

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

أنشئ تطبيق OAuth2 على نسخة Gitea الخاصة بك، ضمن Settings → Applications → Manage OAuth2 applications (أو Site Administration → Integrations → Applications لتطبيق على مستوى النسخة بأكملها):

• Application name: مثل Overleaf، ويراه المستخدمون عند تفويضه
• Redirect URIs: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client: مُحدَّد

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

config/variables.env

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

# Gitea Sync Settings
GITEA_SYNC_ENABLED=true
GITEA_SYNC_CLIENT_ID=
GITEA_SYNC_CLIENT_SECRET=

# Web address of your Gitea (its ROOT_URL), defaults to https://gitea.com
# GITEA_SYNC_URL=https://gitea.example.com

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

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

يطلب Overleaf كل ما تحتاجه المزامنة عندما يربط المستخدم حسابه، لذا لن يحتاج المستخدمون أبدًا إلى إعادة الربط بسبب صلاحية ناقصة:

النطاق	يُستخدم لـ
write:repository	المستودعات وملفاتها (بما في ذلك سير عمل CI ضمن .gitea/workflows) والفروع وطلبات السحب (pull requests)
write:user	إنشاء مستودع للمستخدم عند التصدير (يطلبه Gitea على POST /user/repos)
write:organization	سرد مؤسسات المستخدم وإنشاء مستودع لإحداها عند التصدير

يعرض Gitea هذه النطاقات عندما يفوّض المستخدم التطبيق، ويقصر الرمز عليها.

تنتهي صلاحية رموز الوصول (access tokens) في Gitea بعد ساعة ([oauth2] ACCESS_TOKEN_EXPIRATION_TIME). يجدّدها Overleaf باستخدام رمز التحديث (refresh token) الذي يصدره Gitea معها، حتى عندما يستهلك Gitea رموز التحديث عند استخدامها (INVALIDATE_REFRESH_TOKENS = true)، لذا يبقى المستخدمون مرتبطين إلى أن يلغوا الربط أو يُبطلوا التطبيق في Gitea.

​

نسخة Gitea الخاصة بك

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

المتغير	القيمة الافتراضية
GITEA_SYNC_URL	https://gitea.com
GITEA_SYNC_API_URL	${GITEA_SYNC_URL}/api/v1

يعمل Gitea المُقدَّم تحت مسار فرعي أيضًا، مثل GITEA_SYNC_URL=https://example.com/gitea. لا تضبط GITEA_SYNC_API_URL إلا إذا كانت نسختك تقدّم الواجهة البرمجية (API) في مكان آخر، على سبيل المثال خلف بوابة API.

• أنشئ تطبيق OAuth2 على النسخة التي ضبطتها في GITEA_SYNC_URL، فالتطبيق المُنشأ على نسخة أخرى لا يعمل.
• GITEA_SYNC_URL هو عنوان الويب فقط. لا تُضِف /api/v1 أو مسار مستخدم أو مؤسسة.
• يُودِع Overleaf التغييرات باستخدام واجهة الملفات البرمجية في Gitea، والتي تحتاج إلى محرر الويب: أبقِ [repository.editor] مفعّلًا (وهو الإعداد الافتراضي).

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

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

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

​

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

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

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

• يتواصل Overleaf مع Gitea باستخدام حساب Gitea الخاص بالمستخدم الذي يُجري المزامنة، لذا يربط كل متعاون يُجري المزامنة حسابه الخاص على Gitea، ويجب أن يكون مسموحًا له بالدفع إلى الفرع الافتراضي للمستودع.
• لا يمكن للمتعاونين الذين لديهم صلاحية العرض فقط استخدام المزامنة مع Gitea لهذا المشروع.
• يؤدي إلغاء ربط الحساب في Overleaf إلى نسيان رمزه؛ ولا يوفّر Gitea واجهة برمجية لإبطاله، لذا أبطِل التفويض أيضًا ضمن Settings → Applications في Gitea إذا أردت ذلك.

​

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

• الصلاحيات: يجب أن يكون مسموحًا للمستخدمين بالدفع إلى الفرع الافتراضي للمستودع المرتبط. عندما لا تسمح قاعدة حماية الفرع للمستخدم بالدفع إليه، يطلب منه Overleaf التواصل مع مالك المشروع، كما هو الحال مع مستودع فقد الوصول إليه.
• الدمج: عندما يتغيّر المشروع في كلٍّ من Overleaf وGitea، يُودِع Overleaf تغييراته في فرع مؤقت باسم overleaf-YYYY-MM-DD-HHMMSS ويدمجه عبر طلب سحب (pull request) بأسلوب الدمج الافتراضي للمستودع، لأن Gitea لا يوفّر واجهة برمجية لدمج الفروع دون طلب سحب. بعد الدمج، يحذف Overleaf الفرع المؤقت؛ ويبقى طلب السحب المُدمَج في المستودع كسجلّ.
• قواعد الدمج: لا يتجاوز Overleaf أبدًا حماية الفروع الخاصة بالمستودع. عندما يحتوي طلب السحب على تعارض، أو يتطلب موافقات أو نجاح عمليات التحقق من الحالة، فإنه يبقى مفتوحًا ويطلب Overleaf من المستخدم دمجه في Gitea، ثم متابعة المزامنة.
• سير عمل CI: لا يعرض Overleaf الملفات النقطية (dotfiles) مثل .gitea/workflows/، ويتركها كما هي في المستودع. وتُطلق الإيداعات (commits) القادمة من Overleaf إجراءات Gitea Actions مثل أي إيداع آخر.

​

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

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

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

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

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

هل تدعم المزامنة مع Gitea تقنية Git LFS؟

الإجابة: لا. لا تدعم مشاريع Overleaf تقنية Git Large File Storage. تظهر الملفات التي يتتبعها Git LFS في Overleaf كملفات مؤشرات LFS (pointer files)، وليس بمحتوياتها الفعلية. لذا أودِع الصور وملفات PDF في المستودع مباشرةً بدلًا من ذلك.

هل تعمل مع مستودعات SHA-256؟

الإجابة: ليس بعد. يقارن Overleaf الملفات بمعرّفات SHA-1 الخاصة بها، لذا في المستودع المُنشأ بتنسيق كائنات SHA-256 يعيد كل سحب كتابة جميع الملفات، حتى غير المتغيّرة منها. لا يُفقد شيء، لكن يُرجى استخدام تنسيق SHA-1 الافتراضي.

هل تعمل مع Forgejo؟

الإجابة: بُنيت المزامنة مع Gitea واختُبرت على Gitea فقط.