agenteye-enterprise GitHub organization; once your organization is granted access, each developer or operator generates and rotates their own token, so access stays auditable and revocable per person.
Set the token as an environment variable and Docker credential once per machine:
Username note: GHCR ignores thedocker loginusername and authenticates entirely from the token, so any non-empty value works. These docs use-u xfor brevity; deployment manifests that create a Kubernetes image-pull secret may use a more descriptive username such asagenteye-enterprise. Either is accepted.
Option A: Classic Token (Recommended)
A classic token is the most reliable choice for AgentEye, because GHCR’sdocker login and image-pull flow has the broadest, most consistent support for classic tokens. Two scopes cover everything you need (pulling images and downloading release assets), so you authenticate once and move on without troubleshooting registry quirks. One of them, read:packages, is genuinely read-only; the other, repo, is the only classic scope that grants access to private release assets, and it is deliberately broad — GitHub defines it as full control (read and write) of private repositories.
1. Create the token
Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic).| Field | Value |
|---|---|
| Note | agenteye-<machine-or-team-name> (e.g. agenteye-prod-server) |
| Expiration | Set an expiry appropriate for your security policy; 90 days is a reasonable default |
Label note: GitHub labels this field Note for classic tokens and Token name for fine-grained tokens. They serve the same purpose: a human-readable identifier for later auditing and revocation.
2. Select scopes
| Scope | Why it is needed |
|---|---|
read:packages | Pull Docker images from ghcr.io/agenteye-enterprise/ and download package assets |
repo | Read private repository contents, raw files, and release assets from agenteye-enterprise/releases. This is GitHub’s broad “Full control of private repositories” scope (read and write), not a read-only scope — it is simply the only classic scope that grants access to private release assets |
3. Generate and copy the token
Click Generate token and copy the value immediately; it is shown only once. Store it in your secret manager or environment.Option B: Fine-Grained Token
Fine-grained tokens scope access to specific repositories and permissions, making them the tightest least-privilege option. Choose this path when your organization’s security policy mandates fine-grained tokens.Note: GHCR support for fine-grained tokens is less consistent than for classic tokens. Ifdocker loginordocker pullfails after following these steps, fall back to a classic token (Option A).
1. Create the token
Go to GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.| Field | Value |
|---|---|
| Token name | agenteye-<machine-or-team-name> (e.g. agenteye-prod-server) |
| Expiration | Set an expiry appropriate for your security policy; 90 days is a reasonable default |
| Resource owner | agenteye-enterprise |
| Repository access | Only select repositories → agenteye-enterprise/releases |
2. Set repository permissions
Under Permissions → Repository permissions, set:| Permission | Access |
|---|---|
| Contents | Read-only |
| Packages | Read-only |
Note: If the container images (ghcr.io/agenteye-enterprise/...) are published as organization-level packages rather than repository-linked packages, Docker login may fail with repository-scoped permissions alone. In that case, add an organization-level permission: Permissions → Organization permissions → Packages: Read-only.
3. What each permission grants
| Permission | Used for |
|---|---|
| Contents: Read-only | Downloading docker-compose.yml, release binaries, and Python wheels from agenteye-enterprise/releases |
| Packages: Read-only | Pulling Docker images from ghcr.io/agenteye-enterprise/ |
4. Generate and copy the token
Click Generate token and copy the value immediately; it is shown only once. Store it in your secret manager or environment.Rotating a Token
Rotating tokens on a schedule keeps access auditable and limits the blast radius if a credential ever leaks. Tokens can also expire or be revoked at any time, so rotation is the routine way to stay authenticated. To rotate:- Generate a new token using the steps above.
- Update
AGENTEYE_TOKENin your environment or secret manager. - Re-authenticate Docker:
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin - Revoke the old token in GitHub → Settings → Developer settings → Personal access tokens, then open the Tokens (classic) or Fine-grained tokens sub-page matching the token’s type and delete it.
Verify Your Token
Confirm the token works before wiring it into a deployment, so authentication failures surface here rather than mid-rollout. Each command exercises one of the scopes above:docker login confirms the package scope; a downloaded file confirms the contents scope.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
docker login returns 401 | Token missing Packages: Read-only (fine-grained) or read:packages (classic) | Add the package scope and regenerate |
curl returns 404 on raw GitHub URLs | Token missing Contents: Read-only or repo scope | Add the contents scope and regenerate |
gh release download returns 403 | Token not authorized for agenteye-enterprise/releases | Verify the repo is included in the fine-grained token’s repository access, or use a classic token with repo scope |
| Token accepted but images not found | Org-level package permission missing on fine-grained token | Add organization-level Packages: Read-only permission |
support@exosphere.host.