Documentação do ChatGPT
Português
Contacto goolvyouyou@gmail.com

Manter a autenticação da conta Codex em CI/CD (avançado)

Utilize o fluxo de atualização integrado do Codex para manter o auth.json funcional em executores de CI/CD fidedignos

Este guia mostra como manter a autenticação do Codex gerida pelo ChatGPT funcional num executor de CI/CD fidedigno, sem invocar diretamente o ponto final de tokens OAuth.

A forma correta de autenticar a automatização é através de uma API key. Utilize este guia apenas se precisar especificamente de executar o fluxo de trabalho como a sua conta Codex.

O padrão é o seguinte:

  1. Crie auth.json uma vez numa máquina fidedigna com codex login.
  2. Coloque esse ficheiro no executor.
  3. Execute o Codex normalmente.
  4. Permita que o Codex atualize a sessão quando esta ficar obsoleta.
  5. Guarde o auth.json atualizado para a execução seguinte.

Este é um fluxo de trabalho avançado para empresas e outras automatizações privadas fidedignas. As API keys continuam a ser a opção recomendada para a maioria das tarefas de CI/CD.

Por que motivo isto funciona

O Codex já sabe como atualizar uma sessão gerida pelo ChatGPT.

Na versão atual do cliente de código aberto:

  • o Codex carrega a cache de autenticação local a partir de auth.json
  • se last_refresh tiver mais de cerca de 8 dias, o Codex atualiza o conjunto de tokens antes de a execução continuar
  • após uma atualização bem-sucedida, o Codex escreve os novos tokens e um novo last_refresh novamente em auth.json
  • se um pedido receber um 401, o Codex também dispõe de um fluxo integrado de atualização e nova tentativa

Isto significa que a estratégia de CI/CD suportada não consiste em «invocar diretamente a API de atualização». Consiste em «executar o Codex e conservar o auth.json atualizado».

Quando utilizar este método

Utilize este guia apenas quando todas as condições seguintes forem verdadeiras:

  • precisa da autenticação do Codex gerida pelo ChatGPT em vez de uma API key
  • codex login não pode ser executado no executor remoto
  • o executor é uma infraestrutura privada fidedigna
  • consegue conservar o auth.json atualizado entre execuções
  • apenas uma máquina ou um fluxo de tarefas serializado utilizará uma determinada cópia de auth.json

Este guia aplica-se à autenticação do ChatGPT gerida pelo Codex (auth_mode: "chatgpt").

Não se aplica a:

  • autenticação por API key
  • integrações de anfitrião com tokens externos (auth_mode: "chatgptAuthTokens")
  • clientes OAuth genéricos externos ao Codex

Se as suas credenciais estiverem armazenadas no porta-chaves do sistema operativo, mude primeiro para o armazenamento baseado em ficheiros. Consulte Armazenamento de credenciais.

Criar uma vez o auth.json inicial

Numa máquina fidedigna onde seja possível iniciar sessão através do navegador:

  1. Configure o Codex para armazenar as credenciais num ficheiro:
cli_auth_credentials_store = "file"
  1. Execute:
codex login
  1. Verifique se o ficheiro se assemelha a uma autenticação do ChatGPT gerida:
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"

Continue apenas se:

  • auth_mode for "chatgpt"
  • has_refresh_token for true

Em seguida, coloque o conteúdo de auth.json no gestor de segredos de CI/CD ou copie-o para um executor persistente fidedigno.

Padrão recomendado: GitHub Actions num executor autoalojado

A configuração totalmente automatizada mais simples consiste num executor autoalojado do GitHub Actions com um CODEX_HOME persistente.

Por que motivo este padrão funciona bem:

  • o executor pode manter auth.json no disco entre tarefas
  • o Codex pode atualizar o ficheiro no próprio local
  • as tarefas posteriores utilizam automaticamente os tokens atualizados
  • só precisa do segredo original para a inicialização ou uma nova criação dos dados iniciais

O aspeto fundamental é criar o auth.json inicial apenas se estiver em falta. Se reescrever o ficheiro a partir do segredo original em cada execução, perde os tokens atualizados que o Codex acabou de escrever.

Exemplo de fluxo de trabalho agendado:

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

O que isto faz:

  • a primeira execução cria o auth.json inicial
  • as execuções posteriores reutilizam o mesmo ficheiro
  • assim que a sessão em cache for suficientemente antiga, o Codex atualiza-a durante o passo codex exec normal
  • o ficheiro atualizado permanece no disco para a execução seguinte do fluxo de trabalho

Normalmente, um agendamento semanal é suficiente, porque o Codex considera a sessão obsoleta após cerca de 8 dias na versão atual do cliente de código aberto.

Executores efémeros: restaurar, executar o Codex e conservar o ficheiro atualizado

Se utilizar executores alojados no GitHub, executores partilhados do GitLab ou qualquer outro ambiente efémero, o sistema de ficheiros do executor desaparece após cada tarefa. Nessa configuração, é necessário um processo de ida e volta:

  1. restaure o auth.json atual a partir do armazenamento seguro
  2. execute o Codex
  3. escreva o auth.json atualizado novamente no armazenamento seguro

Estrutura genérica do 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"

O requisito fundamental é que o passo de escrita guarde o ficheiro atualizado que o Codex produziu durante a execução, e não os dados iniciais originais.

Não precisa de um comando de atualização separado

Qualquer execução normal do Codex pode atualizar a sessão.

Isto significa que tem duas boas opções:

  • permitir que a sua tarefa existente do Codex em CI/CD atualize o ficheiro naturalmente
  • adicionar uma tarefa de manutenção agendada e simples, como no exemplo do GitHub Actions acima, se as tarefas reais não forem executadas com frequência suficiente

A primeira execução do Codex após a sessão ficar obsoleta é aquela que atualiza auth.json.

Regras operacionais importantes

  • Utilize um auth.json por executor ou por fluxo de trabalho serializado.
  • Não partilhe o mesmo ficheiro entre tarefas simultâneas ou várias máquinas.
  • Não substitua o ficheiro atualizado de um executor persistente pelos dados iniciais originais em cada execução.
  • Não armazene auth.json no repositório, nos registos ou no armazenamento público de artefactos.
  • Volte a criar os dados iniciais a partir de uma máquina fidedigna se a atualização integrada deixar de funcionar.

O que fazer quando a atualização deixar de funcionar

Este fluxo reduz o trabalho manual, mas não garante que a mesma sessão dure para sempre.

Volte a criar o auth.json inicial no executor se:

  • o Codex começar a devolver 401 e o executor já não conseguir efetuar a atualização
  • o token de atualização tiver sido revogado ou expirado
  • outra máquina ou tarefa simultânea tiver rodado o token primeiro
  • o processo de ida e volta ao armazenamento seguro tiver falhado e tiver sido restaurado um ficheiro antigo

Para voltar a criar os dados iniciais:

  1. Execute codex login numa máquina fidedigna.
  2. Substitua a cópia de CI/CD armazenada de auth.json.
  3. Permita que a tarefa seguinte do executor continue a utilizar o fluxo de atualização integrado do Codex.

Verificar se o executor está a manter a sessão

Verifique se o executor ainda tem tokens de autenticação gerida e se last_refresh existe:

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"

Se o executor for persistente, deverá observar que o mesmo ficheiro continua a existir entre execuções. Se o executor for efémero, confirme que o passo de escrita está a armazenar o ficheiro atualizado da última tarefa.

Referências do código-fonte

Se quiser verificar este comportamento no cliente de código aberto:

  • codex-rs/core/src/auth.rs abrange a deteção de tokens obsoletos, a atualização automática, a recuperação através de atualização após um erro 401 e a persistência dos tokens atualizados
  • codex-rs/core/src/auth/storage.rs abrange o armazenamento de auth.json baseado em ficheiros