> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# إعداد GitHub Token

> توثيق إعداد GitHub Token في AgentEye.

GitHub Personal Access Token (PAT) هو بيانات الاعتماد الوحيدة التي تفتح جميع عناصر AgentEye. باستخدام رمز واحد، يمكنك سحب صور Docker وتنزيل ملفات الإصدار وتثبيت عجلات Python، دون الحاجة إلى عمليات تسجيل منفصلة لكل مكون ولا أسرار مشتركة يجب تداولها. يتم توزيع جميع عناصر AgentEye من منظمة `agenteye-enterprise` على GitHub؛ بمجرد أن يتم منح مؤسستك حق الوصول، ينشئ كل مطور أو مشغل رمزه الخاص ويديره بشكل مستقل، بحيث يبقى الوصول قابلاً للتدقيق والإلغاء لكل شخص.

عيّن الرمز كمتغير بيئة وبيانات اعتماد Docker مرة واحدة لكل آلة:

```bash theme={null}
export AGENTEYE_TOKEN=<your-github-pat>
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin
```

> **ملاحظة اسم المستخدم:** GHCR يتجاهل اسم المستخدم في `docker login` ويتحقق من الهوية بالكامل من خلال الرمز، لذا فإن أي قيمة غير فارغة تعمل. تستخدم هذه الوثائق `-u x` للإيجاز؛ قد تستخدم بيانات النشر التي تنشئ سر image-pull على Kubernetes اسم مستخدم أكثر وصفياً مثل `agenteye-enterprise`. كلاهما مقبول.

***

## الخيار أ: الرمز الكلاسيكي (موصى به)

الرمز الكلاسيكي هو الخيار الأكثر موثوقية لـ AgentEye، لأن تدفق `docker login` وسحب الصور في GHCR لديه أوسع دعم أكثر اتساقاً للرموز الكلاسيكية. نطاقان يغطيان كل ما تحتاجه (سحب الصور وتنزيل عناصر الإصدار)، لذا تتحقق من الهوية مرة واحدة وتتابع بدون استكشاف أخطاء السجل. أحدهما، `read:packages`، يكون للقراءة فقط حقاً؛ الآخر، `repo`، هو الوحيد من الأنطقة الكلاسيكية التي تمنح الوصول إلى عناصر الإصدار الخاصة، وهو متعمد أن يكون واسعاً — يعرّفه GitHub على أنه تحكم كامل (قراءة وكتابة) للمستودعات الخاصة.

### 1. إنشاء الرمز

انتقل إلى **GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic)**.

| الحقل          | القيمة                                                                            |
| -------------- | --------------------------------------------------------------------------------- |
| **Note**       | `agenteye-<machine-or-team-name>` (مثلاً `agenteye-prod-server`)                  |
| **Expiration** | عيّن تاريخ انتهاء الصلاحية المناسب لسياستك الأمنية؛ 90 يوماً هو الافتراضي المعقول |

> **ملاحظة التسمية:** يسمي GitHub هذا الحقل **Note** للرموز الكلاسيكية و**Token name** للرموز الدقيقة. تخدم الاثنتان نفس الغرض: معرّف يمكن قراءته بشرياً للتدقيق والإلغاء لاحقاً.

### 2. حدد الأنطقة

| النطاق          | السبب في الحاجة إليه                                                                                                                                                                                                                                                                |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read:packages` | سحب صور Docker من `ghcr.io/agenteye-enterprise/` وتنزيل عناصر الحزم                                                                                                                                                                                                                 |
| `repo`          | قراءة محتويات المستودع الخاصة والملفات الأولية وعناصر الإصدار من `agenteye-enterprise/releases`. هذا هو نطاق GitHub الواسع "تحكم كامل بالمستودعات الخاصة" (قراءة وكتابة)، وليس نطاق للقراءة فقط — إنه ببساطة الوحيد من الأنطقة الكلاسيكية الذي يمنح الوصول إلى عناصر الإصدار الخاصة |

لا توجد أنطقة أخرى مطلوبة.

### 3. توليد ونسخ الرمز

انقر على **Generate token** واحسب القيمة على الفور؛ يُعرض مرة واحدة فقط. خزّنها في مدير الأسرار أو بيئتك.

***

## الخيار ب: الرمز الدقيق

الرموز الدقيقة تحدد نطاق الوصول إلى مستودعات وأذونات محددة، مما يجعلها أضيق خيار امتياز أقل. اختر هذا المسار عندما تفوض سياسة أمان مؤسستك الرموز الدقيقة.

> **ملاحظة:** دعم GHCR للرموز الدقيقة أقل اتساقاً من دعم الرموز الكلاسيكية. إذا فشل `docker login` أو `docker pull` بعد اتباع هذه الخطوات، عد إلى رمز كلاسيكي (الخيار أ).

### 1. إنشاء الرمز

انتقل إلى **GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token**.

| الحقل                 | القيمة                                                                            |
| --------------------- | --------------------------------------------------------------------------------- |
| **Token name**        | `agenteye-<machine-or-team-name>` (مثلاً `agenteye-prod-server`)                  |
| **Expiration**        | عيّن تاريخ انتهاء الصلاحية المناسب لسياستك الأمنية؛ 90 يوماً هو الافتراضي المعقول |
| **Resource owner**    | `agenteye-enterprise`                                                             |
| **Repository access** | **Only select repositories** → `agenteye-enterprise/releases`                     |

### 2. تعيين أذونات المستودع

ضمن **Permissions → Repository permissions**، عيّن:

| الإذن        | الوصول      |
| ------------ | ----------- |
| **Contents** | للقراءة فقط |
| **Packages** | للقراءة فقط |

جميع الأذونات الأخرى يمكن أن تبقى **No access**.

> **ملاحظة:** إذا كانت صور الحاويات (`ghcr.io/agenteye-enterprise/...`) منشورة كحزم على مستوى المنظمة بدلاً من الحزم المرتبطة بالمستودع، قد يفشل تسجيل Docker مع الأذونات ذات النطاق المستودع وحدها. في هذه الحالة، أضف إذن على مستوى المنظمة: **Permissions → Organization permissions → Packages: Read-only**.

### 3. ما الذي يمنحه كل إذن

| الإذن                 | المستخدم في                                                                               |
| --------------------- | ----------------------------------------------------------------------------------------- |
| Contents: للقراءة فقط | تنزيل `docker-compose.yml` وملفات الإصدار وعجلات Python من `agenteye-enterprise/releases` |
| Packages: للقراءة فقط | سحب صور Docker من `ghcr.io/agenteye-enterprise/`                                          |

### 4. توليد ونسخ الرمز

انقر على **Generate token** واحسب القيمة على الفور؛ يُعرض مرة واحدة فقط. خزّنها في مدير الأسرار أو بيئتك.

***

## تدوير الرمز

تدوير الرموز على جدول زمني منتظم يحافظ على الوصول قابلاً للتدقيق ويحد من نطاق الضرر إذا تسريب بيانات الاعتماد. يمكن للرموز أيضاً أن تنتهي صلاحيتها أو يتم إلغاؤها في أي وقت، لذا فإن التدوير هو الطريقة الروتينية للبقاء مصرحاً. للقيام بالتدوير:

1. أنشئ رمزاً جديداً باستخدام الخطوات أعلاه.
2. حدّث `AGENTEYE_TOKEN` في بيئتك أو مدير الأسرار.
3. أعد مصادقة Docker: `echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin`
4. ألغِ الرمز القديم في GitHub → Settings → Developer settings → Personal access tokens، ثم افتح صفحة **Tokens (classic)** أو **Fine-grained tokens** الفرعية التي تطابق نوع الرمز وحذفها.

***

## تحقق من رمزك

أكّد أن الرمز يعمل قبل توصيله بنشر، حتى تظهر أخطاء المصادقة هنا بدلاً من منتصف النشر. تمارس كل أمر أحد الأنطقة أعلاه:

```bash theme={null}
# Packages scope - authenticate Docker against GHCR
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin

# Contents scope - fetch a raw release file
curl -fsSL \
  -H "Authorization: token $AGENTEYE_TOKEN" \
  https://raw.githubusercontent.com/agenteye-enterprise/releases/main/docker-compose.yml \
  -o /tmp/agenteye-compose-check.yml
```

يؤكد `docker login` الناجح نطاق الحزمة؛ الملف المحمل يؤكد نطاق المحتويات.

***

## استكشاف الأخطاء

| الأعراض                                 | السبب المحتمل                                                         | الحل                                                                                           |
| --------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `docker login` يعود 401                 | الرمز مفقود `Packages: Read-only` (دقيق) أو `read:packages` (كلاسيكي) | أضف نطاق الحزمة وأعد التوليد                                                                   |
| `curl` يعود 404 على URLs GitHub الأولية | الرمز مفقود `Contents: Read-only` أو نطاق `repo`                      | أضف نطاق المحتويات وأعد التوليد                                                                |
| `gh release download` يعود 403          | الرمز غير مصرح به لـ `agenteye-enterprise/releases`                   | تحقق من أن المستودع مدرج في وصول مستودع الرمز الدقيق، أو استخدم رمزاً كلاسيكياً مع نطاق `repo` |
| الرمز مقبول لكن الصور غير موجودة        | إذن حزمة على مستوى المنظمة مفقود على الرمز الدقيق                     | أضف إذن `Packages: Read-only` على مستوى المنظمة                                                |

للمشاكل المتعلقة بالوصول، اتصل بـ `support@exosphere.host`.