> ## 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 सेटअप

> AgentEye GitHub Token सेटअप दस्तावेज़।

एक GitHub Personal Access Token (PAT) वह एकमात्र credential है जो हर AgentEye artifact को अनलॉक करता है। एक token के साथ आप Docker images pull कर सकते हैं, release binaries डाउनलोड कर सकते हैं, और Python wheels install कर सकते हैं, बिना किसी per-component login और बिना कोई shared secrets circulate किए। सभी AgentEye artifacts `agenteye-enterprise` GitHub organization से distribute किए जाते हैं; एक बार जब आपके organization को access दे दिया जाता है, तो प्रत्येक developer या operator अपना खुद का token generate और rotate करता है, इसलिए access auditable और per-person revocable रहता है।

Token को environment variable के रूप में और Docker credential के रूप में एक बार प्रति machine सेट करें:

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

> **Username नोट:** GHCR `docker login` username को ignore करता है और पूरी तरह से token से authenticate करता है, इसलिए कोई भी non-empty value काम करती है। ये docs संक्षेप के लिए `-u x` का उपयोग करते हैं; deployment manifests जो Kubernetes image-pull secret बनाते हैं वे `agenteye-enterprise` जैसे अधिक descriptive username का उपयोग कर सकते हैं। दोनों स्वीकार हैं।

***

## विकल्प A: Classic Token (अनुशंसित)

एक classic token AgentEye के लिए सबसे विश्वसनीय विकल्प है, क्योंकि GHCR का `docker login` और image-pull flow classic tokens के लिए सबसे व्यापक, सबसे सुसंगत support है। दो scopes सब कुछ cover करते हैं जो आपको चाहिए (images pull करना और release assets डाउनलोड करना), इसलिए आप एक बार authenticate करते हैं और registry quirks की troubleshooting किए बिना आगे बढ़ते हैं। इनमें से एक, `read:packages`, genuinely read-only है; दूसरा, `repo`, एकमात्र classic scope है जो private release assets तक access देता है, और यह deliberately broad है — GitHub इसे private repositories का full control (read और write) के रूप में define करता है।

### 1. Token बनाएँ

**GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic)** पर जाएं।

| Field          | Value                                                                                |
| -------------- | ------------------------------------------------------------------------------------ |
| **Note**       | `agenteye-<machine-or-team-name>` (जैसे `agenteye-prod-server`)                      |
| **Expiration** | अपनी security policy के लिए उपयुक्त expiry सेट करें; 90 दिन एक reasonable default है |

> **Label नोट:** GitHub इस field को classic tokens के लिए **Note** और fine-grained tokens के लिए **Token name** कहता है। वे एक ही purpose serve करते हैं: बाद में auditing और revocation के लिए एक human-readable identifier।

### 2. Scopes चुनें

| Scope           | यह क्यों आवश्यक है                                                                                                                                                                                                                                                                              |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read:packages` | `ghcr.io/agenteye-enterprise/` से Docker images pull करें और package assets डाउनलोड करें                                                                                                                                                                                                        |
| `repo`          | Private repository contents, raw files, और `agenteye-enterprise/releases` से release assets को read करें। यह GitHub का broad "Full control of private repositories" scope (read और write) है, न कि read-only scope — यह बस एकमात्र classic scope है जो private release assets तक access देता है |

कोई अन्य scopes आवश्यक नहीं हैं।

### 3. Token generate और copy करें

**Generate token** पर क्लिक करें और तुरंत value को copy करें; यह केवल एक बार दिखाया जाता है। इसे अपने secret manager या environment में store करें।

***

## विकल्प B: Fine-Grained Token

Fine-grained tokens specific repositories और permissions तक access को scope करते हैं, जिससे वे tightest least-privilege विकल्प बन जाते हैं। इस path को चुनें जब आपके organization की security policy fine-grained tokens को mandate करे।

> **नोट:** Fine-grained tokens के लिए GHCR support classic tokens जितना consistent नहीं है। यदि इन steps को follow करने के बाद `docker login` या `docker pull` fail हो, तो classic token पर fall back करें (विकल्प A)।

### 1. Token बनाएँ

**GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token** पर जाएं।

| Field                 | Value                                                                                |
| --------------------- | ------------------------------------------------------------------------------------ |
| **Token name**        | `agenteye-<machine-or-team-name>` (जैसे `agenteye-prod-server`)                      |
| **Expiration**        | अपनी security policy के लिए उपयुक्त expiry सेट करें; 90 दिन एक reasonable default है |
| **Resource owner**    | `agenteye-enterprise`                                                                |
| **Repository access** | **Only select repositories** → `agenteye-enterprise/releases`                        |

### 2. Repository permissions सेट करें

**Permissions → Repository permissions** के तहत, सेट करें:

| Permission   | Access    |
| ------------ | --------- |
| **Contents** | Read-only |
| **Packages** | Read-only |

सभी अन्य permissions **No access** पर रहे सकते हैं।

> **नोट:** यदि container images (`ghcr.io/agenteye-enterprise/...`) organization-level packages के रूप में publish किए गए हैं न कि repository-linked packages के रूप में, तो Docker login repository-scoped permissions alone के साथ fail हो सकता है। उस स्थिति में, organization-level permission जोड़ें: **Permissions → Organization permissions → Packages: Read-only**।

### 3. प्रत्येक permission क्या देता है

| Permission          | किसके लिए उपयोग किया जाता है                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| Contents: Read-only | `agenteye-enterprise/releases` से `docker-compose.yml`, release binaries, और Python wheels डाउनलोड करना |
| Packages: Read-only | `ghcr.io/agenteye-enterprise/` से Docker images pull करना                                               |

### 4. Token generate और copy करें

**Generate token** पर क्लिक करें और तुरंत value को copy करें; यह केवल एक बार दिखाया जाता है। इसे अपने secret manager या environment में store करें।

***

## Token को Rotate करना

नियमित schedule पर tokens को rotate करना access को auditable रखता है और यदि कोई credential कभी leak हो तो blast radius को सीमित करता है। Tokens expire भी सकते हैं या किसी भी समय revoke किए जा सकते हैं, इसलिए rotation authenticated रहने का routine तरीका है। Rotate करने के लिए:

1. ऊपर दिए गए steps का उपयोग करके एक नया token generate करें।
2. अपने environment या secret manager में `AGENTEYE_TOKEN` को update करें।
3. Docker को फिर से authenticate करें: `echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin`
4. GitHub → Settings → Developer settings → Personal access tokens में पुराने token को revoke करें, फिर token के type से मेल खाने वाले **Tokens (classic)** या **Fine-grained tokens** sub-page को खोलें और इसे delete करें।

***

## अपने Token को Verify करें

इसे deployment में wire करने से पहले confirm करें कि token काम करता है, ताकि authentication failures यहाँ surface हो बजाय mid-rollout के। प्रत्येक command ऊपर दिए गए scopes में से एक का exercise करता है:

```bash theme={null}
# Packages scope - GHCR के विरुद्ध Docker को authenticate करें
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin

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

एक successful `docker login` package scope को confirm करता है; एक downloaded file contents scope को confirm करता है।

***

## Troubleshooting

| Symptom                                      | संभावित कारण                                                                           | Fix                                                                                                                             |
| -------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `docker login` 401 return करता है            | Token में `Packages: Read-only` (fine-grained) या `read:packages` (classic) missing है | Package scope जोड़ें और regenerate करें                                                                                         |
| `curl` raw GitHub URLs पर 404 return करता है | Token में `Contents: Read-only` या `repo` scope missing है                             | Contents scope जोड़ें और regenerate करें                                                                                        |
| `gh release download` 403 return करता है     | Token को `agenteye-enterprise/releases` के लिए authorize नहीं किया गया है              | Verify करें कि repo fine-grained token की repository access में included है, या `repo` scope के साथ classic token का उपयोग करें |
| Token accepted है लेकिन images नहीं मिले     | Fine-grained token पर organization-level package permission missing है                 | Organization-level `Packages: Read-only` permission जोड़ें                                                                      |

Access issues के लिए, `support@exosphere.host` से contact करें।