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 सेट करें:

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 करें

Token को Rotate करना

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

ऊपर दिए गए steps का उपयोग करके एक नया token generate करें।
अपने environment या secret manager में AGENTEYE_TOKEN को update करें।
Docker को फिर से authenticate करें: echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin
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 करता है:

# 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 करें।

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

​1. Token बनाएँ

​2. Scopes चुनें

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

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

​1. Token बनाएँ

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

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

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

​Token को Rotate करना

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

​Troubleshooting

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

1. Token बनाएँ

2. Scopes चुनें

3. Token generate और copy करें

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

1. Token बनाएँ

2. Repository permissions सेट करें

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

4. Token generate और copy करें

Token को Rotate करना

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

Troubleshooting