> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# المزامنة مع GitHub

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

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

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-36.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=fd5305cbb4ea8505b5eab6f41f90a57c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-39.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=1d8103102915872ba94119bb00fa58e0)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-35.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=18c0d0917b5c3768593a608a53b6c19c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-40.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=7ebf71a5528a1b22e1e2c7f17a71b49a)

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

> [!WARNING]
>
> يجب عليك تفعيل [git-bridge](https://ayakaleaf-pro.mintlify.site/ar/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md) أولًا قبل استخدام المزامنة مع GitHub.
>
> ```dotenv title="config/overleaf.rc" theme={null}
> GIT_BRIDGE_ENABLED=true
> ```

انتقل إلى [إعدادات المطورين](https://github.com/settings/developers) لإنشاء تطبيق 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.

```dotenv title="config/variables.env" wrap theme={null}
# 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
```

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

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

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

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

### GitHub Enterprise

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

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

```dotenv title="config/variables.env" wrap theme={null}
# 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` |

> [!WARNING]
>
> * أنشئ تطبيق 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 نفسها.

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

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

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

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

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

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

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

> [accordion] كيف أربط مشروعًا بـ 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**.

> [accordion] هل يمكنني إجراء دفع قسري (force push) إلى الفرع الافتراضي؟
>
> **الإجابة:** لا نوصي بذلك. يكتشف Overleaf الدفع القسري، ويحذّر منه ويتولّى الفرع الذي أُعيدت كتابته، مع دمج التغييرات التي أُجريت في Overleaf منذ آخر مزامنة. لتجنّب المفاجآت، احمِ الفرع الافتراضي من الدفع القسري في إعدادات المستودع.

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

> [accordion] تعرض المزامنة مع GitHub الرسالة "Something wrong with GitHub request"
>
> **الإجابة:** تعني هذه الرسالة أن الخادم لم يتمكن من الوصول إلى GitHub، على سبيل المثال بسبب مشكلة في الشبكة أو DNS أو TLS أو الوكيل. شغّل `bin/logs web` لرؤية الخطأ كاملًا. إذا كان الخادم يحتاج إلى وكيل للوصول إلى GitHub، فاضبط `GITHUB_SYNC_PROXY_URL`.

> [accordion] هل يجب أن أعطّل "Expire user access tokens" في تطبيق GitHub OAuth؟
>
> **الإجابة:** نعم. لا تجدّد المزامنة مع GitHub الرموز المنتهية الصلاحية. مع تفعيل الرموز المنتهية الصلاحية، سيتعين على المستخدمين ربط GitHub مجددًا في كل مرة تنتهي فيها صلاحية رمزهم.

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

> [accordion] يفشل ربط حساب 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` لإعادة إنشاء الحاويات.

> [accordion] يفشل استيراد مستودع مع الرسالة “EmptyZipFileError: empty\_zip\_file” أو “unzip failed”
>
> **الإجابة:** يستورد Overleaf أرشيف zip لآخر إيداع على الفرع الافتراضي للمستودع، ويعني هذا الخطأ أن الأرشيف لا يحتوي على أي ملف يستطيع Overleaf استيراده. تحقّق من الفرع الافتراضي على GitHub:
>
> * أنه يحتوي على ملفات المشروع، وليس فقط ملفات يتخطاها Overleaf عند الاستيراد: الملفات التي تبدأ بنقطة مثل `.gitignore` و`.gitmodules` (يُحتفَظ بـ `.latexmkrc`)، وملفات البناء مثل `*.aux` و`*.log` و`*.bbl` و`*.synctex.gz` و`*.doc` و`*.docx`.
> * أن الملفات ليست موجودة داخل وحدات Git الفرعية (submodules) فقط. إذ يترك أرشيف GitHub الوحدات الفرعية مجلدات فارغة.
> * أن الملفات التي تتوقعها موجودة على الفرع الافتراضي، لا على فرع آخر. يستخدم الاستيراد الفرع الافتراضي دائمًا.

> [accordion] يفشل استيراد مستودع مع الرسالة “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](https://ayakaleaf-pro.mintlify.site/ar/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md)) وأعد إنشاء الحاوية. يضبط Toolkit هذه القيمة مسبقًا؛ تحقّق من أن `docker-compose.override.yml` لا يتجاوزها.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.