Configuración del Token de GitHub

Un Token de Acceso Personal (PAT) de GitHub es la única credencial que desbloquea todos los artefactos de AgentEye. Con un solo token puedes descargar las imágenes Docker, los binarios de las versiones publicadas y los paquetes Python, sin necesidad de iniciar sesión por componente ni de compartir secretos. Todos los artefactos de AgentEye se distribuyen desde la organización agenteye-enterprise en GitHub; una vez que se otorga acceso a tu organización, cada desarrollador u operador genera y rota su propio token, lo que mantiene el acceso auditable y revocable por persona. Configura el token como variable de entorno y credencial de Docker una vez por máquina:

export AGENTEYE_TOKEN=<your-github-pat>
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin

Nota sobre el nombre de usuario: GHCR ignora el nombre de usuario en docker login y se autentica exclusivamente mediante el token, por lo que cualquier valor no vacío funciona. En esta documentación se usa -u x por brevedad; los manifiestos de despliegue que crean un secreto de extracción de imágenes en Kubernetes pueden utilizar un nombre de usuario más descriptivo, como agenteye-enterprise. Ambos son válidos.

Opción A: Token Clásico (Recomendado)

Un token clásico es la opción más fiable para AgentEye, ya que el flujo de docker login e imagen de GHCR tiene el soporte más amplio y consistente para tokens clásicos. Dos alcances cubren todo lo que necesitas (extraer imágenes y descargar artefactos de versiones), de modo que te autenticas una vez y continúas sin tener que resolver problemas del registro. Uno de ellos, read:packages, es genuinamente de solo lectura; el otro, repo, es el único alcance clásico que concede acceso a artefactos de versiones privadas, y es deliberadamente amplio — GitHub lo define como control total (lectura y escritura) de repositorios privados.

1. Crear el token

Ve a GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic).

Campo	Valor
Note	`agenteye-<nombre-de-máquina-o-equipo>` (p. ej. `agenteye-prod-server`)
Expiration	Define un vencimiento acorde a tu política de seguridad; 90 días es un valor predeterminado razonable

Nota sobre la etiqueta: GitHub denomina este campo Note en los tokens clásicos y Token name en los tokens de grano fino. Cumplen el mismo propósito: un identificador legible para auditorías y revocaciones posteriores.

2. Seleccionar los alcances

Alcance	Por qué es necesario
`read:packages`	Extraer imágenes Docker de `ghcr.io/agenteye-enterprise/` y descargar artefactos de paquetes
`repo`	Leer contenidos de repositorios privados, archivos sin procesar y artefactos de versiones de `agenteye-enterprise/releases`. Este es el alcance de GitHub definido como “Control total de repositorios privados” (lectura y escritura), no de solo lectura — es simplemente el único alcance clásico que concede acceso a artefactos de versiones privadas

No se requieren otros alcances.

3. Generar y copiar el token

Haz clic en Generate token y copia el valor de inmediato; solo se muestra una vez. Guárdalo en tu gestor de secretos o en tu entorno.

Opción B: Token de Grano Fino

Los tokens de grano fino limitan el acceso a repositorios y permisos específicos, lo que los convierte en la opción de mínimo privilegio más restrictiva. Elige esta ruta cuando la política de seguridad de tu organización exija tokens de grano fino.

Nota: El soporte de GHCR para tokens de grano fino es menos consistente que para los tokens clásicos. Si docker login o docker pull falla después de seguir estos pasos, recurre a un token clásico (Opción A).

1. Crear el token

Ve a GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.

Campo	Valor
Token name	`agenteye-<nombre-de-máquina-o-equipo>` (p. ej. `agenteye-prod-server`)
Expiration	Define un vencimiento acorde a tu política de seguridad; 90 días es un valor predeterminado razonable
Resource owner	`agenteye-enterprise`
Repository access	Only select repositories → `agenteye-enterprise/releases`

2. Configurar los permisos del repositorio

En Permissions → Repository permissions, establece:

Permiso	Acceso
Contents	Read-only
Packages	Read-only

Todos los demás permisos pueden dejarse en No access.

Nota: Si las imágenes de contenedor (ghcr.io/agenteye-enterprise/...) se publican como paquetes a nivel de organización en lugar de paquetes vinculados a un repositorio, el inicio de sesión de Docker puede fallar únicamente con permisos de alcance de repositorio. En ese caso, agrega un permiso a nivel de organización: Permissions → Organization permissions → Packages: Read-only.

3. Qué concede cada permiso

Permiso	Utilizado para
Contents: Read-only	Descargar `docker-compose.yml`, binarios de versiones y paquetes Python de `agenteye-enterprise/releases`
Packages: Read-only	Extraer imágenes Docker de `ghcr.io/agenteye-enterprise/`

4. Generar y copiar el token

Haz clic en Generate token y copia el valor de inmediato; solo se muestra una vez. Guárdalo en tu gestor de secretos o en tu entorno.

Rotación de un Token

Rotar los tokens de forma periódica mantiene el acceso auditable y limita el impacto en caso de que una credencial se filtre. Los tokens también pueden expirar o revocarse en cualquier momento, por lo que la rotación es la forma habitual de mantenerse autenticado. Para rotar:

Genera un nuevo token siguiendo los pasos anteriores.
Actualiza AGENTEYE_TOKEN en tu entorno o gestor de secretos.
Vuelve a autenticar Docker: echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin
Revoca el token anterior en GitHub → Settings → Developer settings → Personal access tokens, abre la subpágina Tokens (classic) o Fine-grained tokens según el tipo de token y elimínalo.

Verificar tu Token

Confirma que el token funciona antes de integrarlo en un despliegue, de modo que los errores de autenticación aparezcan aquí y no a mitad de una puesta en producción. Cada comando ejercita uno de los alcances anteriores:

# 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

Un docker login exitoso confirma el alcance de paquetes; un archivo descargado correctamente confirma el alcance de contenidos.

Solución de Problemas

Síntoma	Causa probable	Solución
`docker login` devuelve 401	Token sin `Packages: Read-only` (grano fino) o `read:packages` (clásico)	Agrega el alcance de paquetes y regenera el token
`curl` devuelve 404 en URLs de GitHub sin procesar	Token sin `Contents: Read-only` o alcance `repo`	Agrega el alcance de contenidos y regenera el token
`gh release download` devuelve 403	Token no autorizado para `agenteye-enterprise/releases`	Verifica que el repositorio esté incluido en el acceso del token de grano fino, o usa un token clásico con alcance `repo`
Token aceptado pero no se encuentran las imágenes	Falta el permiso de paquetes a nivel de organización en el token de grano fino	Agrega el permiso de organización `Packages: Read-only`

Para problemas de acceso, contacta a support@exosphere.host.

​Opción A: Token Clásico (Recomendado)

​1. Crear el token

​2. Seleccionar los alcances

​3. Generar y copiar el token

​Opción B: Token de Grano Fino

​1. Crear el token

​2. Configurar los permisos del repositorio

​3. Qué concede cada permiso

​4. Generar y copiar el token

​Rotación de un Token

​Verificar tu Token

​Solución de Problemas

Opción A: Token Clásico (Recomendado)

1. Crear el token

2. Seleccionar los alcances

3. Generar y copiar el token

Opción B: Token de Grano Fino

1. Crear el token

2. Configurar los permisos del repositorio

3. Qué concede cada permiso

4. Generar y copiar el token

Rotación de un Token

Verificar tu Token

Solución de Problemas