> ## 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.

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

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

تعمل المزامنة مع Gitea بطريقة مماثلة لـ [المزامنة مع GitHub](https://ayakaleaf-pro.mintlify.site/ar/on-premises/configuration/overleaf-toolkit/github-synchronisation.md) و[المزامنة مع GitLab](https://ayakaleaf-pro.mintlify.site/ar/on-premises/configuration/overleaf-toolkit/gitlab-synchronisation.md): يربط المستخدمون حساباتهم على Gitea، ويصدّرون المشاريع إلى مستودعات Gitea جديدة، ويستوردون مستودعات Gitea، ويزامنون التغييرات في كلا الاتجاهين. وهي تعمل مع Gitea بالإصدار 1.23 أو أحدث، على gitea.com أو على نسختك الخاصة.

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

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

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

> [!WARNING]
>
> قبل تكوين عنوان إعادة التوجيه (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.

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

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

> [!CAUTION]
>
> تنتمي الحسابات والمشاريع المرتبطة إلى النسخة التي رُبطت بها. قبل تبديل `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 فقط.


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