المزامنة مع GitHub

أتِح للمستخدمين مزامنة مشاريعهم مع مستودعات GitHub أو GitHub Enterprise.

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

​

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

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

انتقل إلى إعدادات المطورين لإنشاء تطبيق GitHub OAuth الخاص بك، وانسخ CLIENT_ID وSECRET.

ملاحظة: عند إنشاء تطبيق OAuth، أدخل ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback في Authorization callback URL. يبني Ayakaleaf Pro العنوان نفسه من OVERLEAF_SITE_URL، لذا لا يوجد ما تضبطه له في config/variables.env.

بعد ذلك، أضف الإعدادات التالية إلى ملفات متغيرات البيئة الخاصة بـ overleaf.

config/variables.env

# used to encrypt the user's GitHub access token.
# How to generate: `openssl rand -hex 32`
GITHUB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Github Sync Settings
GITHUB_SYNC_ENABLED=true
GITHUB_SYNC_CLIENT_ID=
GITHUB_SYNC_CLIENT_SECRET=

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

قبل تكوين عنوان URL لاستدعاء GitHub OAuth، تأكد من ضبط OVERLEAF_SITE_URL بشكل صحيح.

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

يجب أن يكون GITHUB_SYNC_PROXY_URL وكيلًا أماميًا قياسيًا من نوع HTTP/HTTPS (مثل منفذ HTTP في Clash). مرايا تنزيل GitHub مثل gh-proxy.org غير مدعومة.

لا تستخدم 127.0.0.1 كمضيف للوكيل. إذا كان الوكيل يعمل على الخادم المضيف، فاستخدم عنوان IP الخاص بالخادم على الشبكة المحلية (مثل 192.168.1.xx) وتأكد من تكوين الوكيل لقبول الاتصالات من الأجهزة على الشبكة المحلية.

​

GitHub Enterprise

دعم GitHub Enterprise متاح بدءًا من الإصدار v6.3.1 وما بعده. تتصل الإصدارات الأقدم بـ github.com فقط، ولا يكون للمتغيرات أدناه أي تأثير.

تتصل المزامنة مع GitHub افتراضيًا بـ github.com. لاستخدام GitHub Enterprise Server (المستضاف ذاتيًا) أو GitHub Enterprise Cloud مع موطن البيانات (data residency) (GHE.com)، اضبط GITHUB_SYNC_URL على عنوان الويب الخاص بنسختك، أي العنوان الذي تفتح به المستودعات في المتصفح.

config/variables.env

# GitHub Enterprise Server
GITHUB_SYNC_URL=https://github.example.com

# or GitHub Enterprise Cloud with data residency
# GITHUB_SYNC_URL=https://octocorp.ghe.com

تُشتق نقاط نهاية REST وGraphQL API من GITHUB_SYNC_URL بالطريقة نفسها التي تتبعها GitHub CLI:

GITHUB_SYNC_URL	REST API	GraphQL API
https://github.com (افتراضي)	https://api.github.com	https://api.github.com/graphql
https://SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com/graphql
https://HOST (أي عنوان آخر)	https://HOST/api/v3	https://HOST/api/graphql

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

المتغير	القيمة الافتراضية
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	مُشتق من GITHUB_SYNC_URL، راجع الجدول أعلاه
GITHUB_SYNC_GRAPHQL_URL	مُشتق من GITHUB_SYNC_API_URL عند ضبطه (يصبح /api/v3 هو /api/graphql، وإلا يُلحَق /graphql)، وإلا فمن GITHUB_SYNC_URL

• أنشئ تطبيق OAuth على نسخة المؤسسة الخاصة بك (Settings → Developer settings → OAuth Apps)، فالتطبيق المُنشأ على github.com لا يعمل هناك. عنوان URL لاستدعاء OAuth هو نفسه: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL هو عنوان الويب فقط. لا تضبطه على عنوان API مثل https://api.github.com أو https://HOST/api/v3، ولا تُضِف مسار مؤسسة (organisation).
• يجب أن تشير العناوين الثلاثة جميعها إلى نسخة GitHub نفسها.

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

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

​

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

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

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

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

​

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

كيف أربط مشروعًا بـ GitHub وأزامنه؟

الإجابة: في المحرر، افتح Integrations وانقر على GitHub. إذا لم يكن حساب GitHub الخاص بك مرتبطًا بعد، فانقر أولًا على Link to your GitHub account. في Export Project to GitHub، أدخل اسمًا للمستودع، واختر Private ضمن Repository visibility، ثم انقر على Create a GitHub repository.

بعد ذلك، تفتح البطاقة نفسها Sync with GitHub، التي تسرد الإيداعات (commits) الجديدة في GitHub. انقر على Sync لإيداع تغييراتك في Overleaf في الفرع الافتراضي وجلب تغييرات GitHub إلى المشروع. تعمل المزامنة في الاتجاهين، لكنها لا تُنفَّذ إلا عندما ينقر أحدهم على Sync؛ فلا توجد مزامنة مجدولة. عندما يتغير الجانبان كلاهما، يدمج Overleaf التغييرات عبر فرع مؤقت باسم overleaf-YYYY-MM-DD-HHMMSS. إذا حدث تعارض في هذا الدمج، فادمج الفرع في GitHub بنفسك، ثم انقر على I have manually merged. Continue.

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

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

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

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

تعرض المزامنة مع GitHub الرسالة "Something wrong with GitHub request"

الإجابة: تعني هذه الرسالة أن الخادم لم يتمكن من الوصول إلى GitHub، على سبيل المثال بسبب مشكلة في الشبكة أو DNS أو TLS أو الوكيل. شغّل bin/logs web لرؤية الخطأ كاملًا. إذا كان الخادم يحتاج إلى وكيل للوصول إلى GitHub، فاضبط GITHUB_SYNC_PROXY_URL.

هل يجب أن أعطّل "Expire user access tokens" في تطبيق GitHub OAuth؟

الإجابة: نعم. لا تجدّد المزامنة مع GitHub الرموز المنتهية الصلاحية. مع تفعيل الرموز المنتهية الصلاحية، سيتعين على المستخدمين ربط GitHub مجددًا في كل مرة تنتهي فيها صلاحية رمزهم.

هل يجب أن تكون نسختي قابلة للوصول من الإنترنت؟

الإجابة: لا. يتم ربط الحساب عبر متصفح المستخدم، لذا يكفي أن يُفتح عنوان استدعاء OAuth في متصفح المستخدم. يحتاج الخادم فقط إلى الوصول إلى GitHub؛ وإذا احتاج إلى وكيل لذلك، فاضبط GITHUB_SYNC_PROXY_URL. لا يتصل GitHub بنسختك أبدًا: لا يُزامَن المشروع إلا عندما يزامنه المستخدم في المحرر.

يفشل ربط حساب GitHub الخاص بي أو يعيدني دون إتمام الربط

الإجابة: تحقّق مما يلي بالترتيب:

• افتح Overleaf على العنوان المضبوط في OVERLEAF_SITE_URL تمامًا. يعيدك GitHub إلى ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback، ولا تكون جلسة تسجيل دخولك موجودة إلا على العنوان الذي بدأت منه، لذا فإن أي مضيف أو عنوان IP أو منفذ آخر سينتهي بك إلى صفحة تسجيل الدخول أو إلى الرسالة “Restricted, sorry you don’t have permission to load this page”.
• يجب أن يكون Authorization callback URL الخاص بتطبيق OAuth هو ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback، بالمخطط والمضيف والمنفذ نفسها.
• تعني صفحة الخطأ التي تتضمن Failed to obtain access token from Git server أن GitHub لم يُعِد رمزًا مميزًا: تحقّق من GITHUB_SYNC_CLIENT_ID وGITHUB_SYNC_CLIENT_SECRET، ومن أن الخادم يستطيع الوصول إلى GitHub. شغّل bin/logs web لرؤية الخطأ كاملًا.

بعد تغيير config/variables.env، شغّل bin/up لإعادة إنشاء الحاويات.

يفشل استيراد مستودع مع الرسالة “EmptyZipFileError: empty_zip_file” أو “unzip failed”

الإجابة: يستورد Overleaf أرشيف zip لآخر إيداع على الفرع الافتراضي للمستودع، ويعني هذا الخطأ أن الأرشيف لا يحتوي على أي ملف يستطيع Overleaf استيراده. تحقّق من الفرع الافتراضي على GitHub:

• أنه يحتوي على ملفات المشروع، وليس فقط ملفات يتخطاها Overleaf عند الاستيراد: الملفات التي تبدأ بنقطة مثل .gitignore و.gitmodules (يُحتفَظ بـ .latexmkrc)، وملفات البناء مثل *.aux و*.log و*.bbl و*.synctex.gz و*.doc و*.docx.
• أن الملفات ليست موجودة داخل وحدات Git الفرعية (submodules) فقط. إذ يترك أرشيف GitHub الوحدات الفرعية مجلدات فارغة.
• أن الملفات التي تتوقعها موجودة على الفرع الافتراضي، لا على فرع آخر. يستخدم الاستيراد الفرع الافتراضي دائمًا.

يفشل استيراد مستودع مع الرسالة “connect ECONNREFUSED” إلى “sharelatex:3054”

الإجابة: القيمة المضبوطة لـ V1_HISTORY_URL هي http://sharelatex:3054، وهي قيمة وردت في إصدارات أقدم من هذه الوثائق. المنفذ 3054 هو خدمة project-history، التي لا تستمع إلا داخل الحاوية، بينما يجب أن يشير V1_HISTORY_URL إلى history-v1. يحفظ Overleaf كل ملف ثنائي (الصور وملفات PDF) من المستودع المستورَد في history-v1، لذا يفشل الاستيراد؛ كما يفشل رفع مثل هذا الملف في المحرر بالطريقة نفسها. في ملف docker-compose.yml الخاص بك، اضبط V1_HISTORY_URL: "http://sharelatex:3100/api" على الخدمة sharelatex (راجع التكامل مع Git) وأعد إنشاء الحاوية. يضبط Toolkit هذه القيمة مسبقًا؛ تحقّق من أن docker-compose.override.yml لا يتجاوزها.