Documentación de ChatGPT
Español
Contacto goolvyouyou@gmail.com

Mantener la autenticación de la cuenta de Codex en CI/CD (avanzado)

Usa el flujo de actualización integrado de Codex para mantener auth.json operativo en ejecutores de CI/CD de confianza

Esta guía muestra cómo mantener operativa la autenticación de Codex administrada por ChatGPT en un ejecutor de CI/CD de confianza sin llamar directamente al punto de conexión de tokens de OAuth.

La forma correcta de autenticar la automatización es mediante una API key. Usa esta guía solo si necesitas específicamente ejecutar el flujo de trabajo con tu cuenta de Codex.

El patrón es el siguiente:

  1. Crea auth.json una vez en una máquina de confianza con codex login.
  2. Coloca ese archivo en el ejecutor.
  3. Ejecuta Codex con normalidad.
  4. Deja que Codex actualice la sesión cuando quede obsoleta.
  5. Conserva el archivo auth.json actualizado para la siguiente ejecución.

Este es un flujo de trabajo avanzado para empresas y otros entornos privados de automatización de confianza. Las API keys siguen siendo la opción recomendada para la mayoría de los trabajos de CI/CD.

Por qué funciona

Codex ya sabe cómo actualizar una sesión administrada por ChatGPT.

En la versión actual del cliente de código abierto:

  • Codex carga la caché de autenticación local desde auth.json
  • si last_refresh tiene más de unos 8 días, Codex actualiza el conjunto de tokens antes de que continúe la ejecución
  • después de una actualización correcta, Codex vuelve a escribir los tokens nuevos y un nuevo last_refresh en auth.json
  • si una solicitud recibe un 401, Codex también dispone de una ruta integrada de actualización y reintento

Esto significa que la estrategia de CI/CD compatible no es «llamar directamente a la API de actualización». Es «ejecutar Codex y conservar el archivo auth.json actualizado».

Cuándo usar esta guía

Usa esta guía solo cuando se cumplan todas las condiciones siguientes:

  • necesitas la autenticación de Codex administrada por ChatGPT en lugar de una API key
  • codex login no puede ejecutarse en el ejecutor remoto
  • el ejecutor es una infraestructura privada de confianza
  • puedes conservar el archivo auth.json actualizado entre ejecuciones
  • solo una máquina o un flujo de trabajos serializado utilizará una copia determinada de auth.json

Esta guía se aplica a la autenticación de ChatGPT administrada por Codex (auth_mode: "chatgpt").

No se aplica a:

  • la autenticación mediante API key
  • las integraciones de host con tokens externos (auth_mode: "chatgptAuthTokens")
  • los clientes OAuth genéricos externos a Codex

Si tus credenciales están almacenadas en el llavero del sistema operativo, cambia primero al almacenamiento basado en archivos. Consulta Almacenamiento de credenciales.

Inicializar auth.json una vez

En una máquina de confianza donde sea posible iniciar sesión mediante el navegador:

  1. Configura Codex para almacenar las credenciales en un archivo:
cli_auth_credentials_store = "file"
  1. Ejecuta:
codex login
  1. Comprueba que el archivo tenga el aspecto de una autenticación de ChatGPT administrada:
AUTH_FILE="${CODEX_HOME:-$HOME/.codex}/auth.json"

jq '{
  auth_mode,
  has_tokens: (.tokens != null),
  has_refresh_token: ((.tokens.refresh_token // "") != ""),
  last_refresh
}' "$AUTH_FILE"

Continúa solo si:

  • auth_mode es "chatgpt"
  • has_refresh_token es true

A continuación, coloca el contenido de auth.json en el gestor de secretos de CI/CD o cópialo en un ejecutor persistente de confianza.

Patrón recomendado: GitHub Actions en un ejecutor autohospedado

La configuración totalmente automatizada más sencilla es un ejecutor autohospedado de GitHub Actions con un CODEX_HOME persistente.

Por qué funciona bien este patrón:

  • el ejecutor puede conservar auth.json en el disco entre trabajos
  • Codex puede actualizar el archivo donde se encuentra
  • los trabajos posteriores usan automáticamente los tokens actualizados
  • solo necesitas el secreto original para la inicialización o una nueva inicialización

El detalle fundamental es inicializar auth.json solo si no existe. Si reescribes el archivo desde el secreto original en cada ejecución, descartas los tokens actualizados que Codex acaba de escribir.

Ejemplo de flujo de trabajo programado:

name: Keep Codex auth fresh

on:
  schedule:
    - cron: "0 9 * * 1"
  workflow_dispatch:

jobs:
  keep-codex-auth-fresh:
    runs-on: self-hosted
    steps:
      - name: Bootstrap auth.json if needed
        shell: bash
        env:
          CODEX_AUTH_JSON: ${{ secrets.CODEX_AUTH_JSON }}
        run: |
          export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
          mkdir -p "$CODEX_HOME"
          chmod 700 "$CODEX_HOME"

          if [ ! -f "$CODEX_HOME/auth.json" ]; then
            printf '%s' "$CODEX_AUTH_JSON" > "$CODEX_HOME/auth.json"
            chmod 600 "$CODEX_HOME/auth.json"
          fi

      - name: Run Codex
        shell: bash
        run: |
          codex exec --json "Reply with the single word OK." >/dev/null

Qué hace:

  • la primera ejecución inicializa auth.json
  • las ejecuciones posteriores reutilizan el mismo archivo
  • cuando la sesión almacenada en caché alcanza la antigüedad suficiente, Codex la actualiza durante el paso normal codex exec
  • el archivo actualizado permanece en el disco para la siguiente ejecución del flujo de trabajo

Una programación semanal suele ser suficiente porque Codex considera que la sesión está obsoleta después de aproximadamente 8 días en el cliente de código abierto actual.

Ejecutores efímeros: restaurar, ejecutar Codex y conservar el archivo actualizado

Si utilizas ejecutores alojados en GitHub, ejecutores compartidos de GitLab o cualquier otro entorno efímero, el sistema de archivos del ejecutor desaparece después de cada trabajo. En esa configuración, necesitas un proceso de ida y vuelta:

  1. restaura el archivo auth.json actual desde un almacenamiento seguro
  2. ejecuta Codex
  3. vuelve a guardar el archivo auth.json actualizado en el almacenamiento seguro

Estructura genérica de GitHub Actions:

name: Run Codex with managed auth

on:
  workflow_dispatch:

jobs:
  codex-job:
    runs-on: ubuntu-latest
    steps:
      - name: Restore auth.json
        shell: bash
        run: |
          export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
          mkdir -p "$CODEX_HOME"
          chmod 700 "$CODEX_HOME"

          # Replace this with your secret manager or secure storage command.
          my-secret-cli read codex-auth-json > "$CODEX_HOME/auth.json"
          chmod 600 "$CODEX_HOME/auth.json"

      - name: Run Codex
        shell: bash
        run: |
          codex exec --json "summarize the failing tests"

      - name: Persist refreshed auth.json
        if: always()
        shell: bash
        run: |
          # Replace this with your secret manager or secure storage command.
          my-secret-cli write codex-auth-json < "$CODEX_HOME/auth.json"

El requisito clave es que el paso de escritura posterior almacene el archivo actualizado que Codex generó durante la ejecución, no la inicialización original.

No necesitas un comando de actualización independiente

Cualquier ejecución normal de Codex puede actualizar la sesión.

Esto significa que tienes dos buenas opciones:

  • dejar que tu trabajo existente de Codex en CI/CD actualice el archivo de forma natural
  • añadir un trabajo ligero de mantenimiento programado, como el ejemplo de GitHub Actions anterior, si tus trabajos reales no se ejecutan con suficiente frecuencia

La primera ejecución de Codex después de que la sesión quede obsoleta es la que actualiza auth.json.

Reglas operativas importantes

  • Usa un auth.json por ejecutor o por flujo de trabajo serializado.
  • No compartas el mismo archivo entre trabajos simultáneos o varias máquinas.
  • No sobrescribas en cada ejecución el archivo actualizado de un ejecutor persistente con la inicialización original.
  • No almacenes auth.json en el repositorio, los registros ni el almacenamiento público de artefactos.
  • Vuelve a inicializar desde una máquina de confianza si la actualización integrada deja de funcionar.

Qué hacer cuando la actualización deja de funcionar

Este flujo reduce el trabajo manual, pero no garantiza que la misma sesión dure para siempre.

Vuelve a inicializar el ejecutor con un auth.json nuevo si:

  • Codex empieza a devolver 401 y el ejecutor ya no puede realizar la actualización
  • el token de actualización se revocó o caducó
  • otra máquina o un trabajo simultáneo rotó primero el token
  • el proceso de ida y vuelta al almacenamiento seguro falló y se restauró un archivo antiguo

Para volver a inicializar:

  1. Ejecuta codex login en una máquina de confianza.
  2. Sustituye la copia de CI/CD almacenada de auth.json.
  3. Deja que el siguiente trabajo del ejecutor continúe usando el flujo de actualización integrado de Codex.

Comprobar que el ejecutor mantiene la sesión

Comprueba que el ejecutor aún tenga tokens de autenticación administrados y que exista last_refresh:

AUTH_FILE="${CODEX_HOME:-$HOME/.codex}/auth.json"

jq '{
  auth_mode,
  last_refresh,
  has_access_token: ((.tokens.access_token // "") != ""),
  has_id_token: ((.tokens.id_token // "") != ""),
  has_refresh_token: ((.tokens.refresh_token // "") != "")
}' "$AUTH_FILE"

Si tu ejecutor es persistente, deberías ver que el mismo archivo sigue existiendo entre ejecuciones. Si tu ejecutor es efímero, confirma que el paso de escritura posterior almacena el archivo actualizado del último trabajo.

Referencias de origen

Si quieres verificar este comportamiento en el cliente de código abierto:

  • codex-rs/core/src/auth.rs abarca la detección de tokens obsoletos, la actualización automática, la recuperación mediante actualización tras un error 401 y la conservación de los tokens actualizados
  • codex-rs/core/src/auth/storage.rs abarca el almacenamiento de auth.json basado en archivos