Esta página foi traduzida automaticamente do inglês. Leia o original em inglês.

Publicação Confiável

Publique pacotes do AI Game Dev via GitHub Actions ou GitLab CI sem token armazenado: configure um publicador confiável, workflows e a proveniência.

Atualizado em 19 de novembro de 2026 Ver como Markdown

O Trusted Publishing permite que um job de CI publique seu pacote sem nenhum segredo armazenado na CI: o GitHub Actions ou o GitLab CI atesta qual repositório e workflow está em execução, e o ai-game.dev troca essa prova por uma credencial de curta duração capaz de enviar um pacote. Toda versão publicada dessa forma registra sua proveniência: o repositório, o commit e a execução de CI a partir dos quais ela foi construída. Esta página mostra como configurá-lo para GitHub e GitLab, e o que é verificado.

Como funciona

  1. Você informa ao registro qual repositório e workflow podem publicar um pacote: um publicador confiável.
  2. Seu job de CI executa gamedev pkg publish sem nenhum token de publicador. A CLI detecta que está rodando no GitHub Actions (ACTIONS_ID_TOKEN_REQUEST_URL) ou no GitLab CI (AIGD_ID_TOKEN) e pede à CI um token de identidade OIDC com a audience ai-game.dev.
  3. A CLI envia esse token para POST /api/registry/v1/oidc/token. O registro o verifica (emissor, assinatura, audience ai-game.dev, validade) e o compara com os publicadores confiáveis do pacote.
  4. Em caso de correspondência, ele retorna uma credencial (agd_oidc_…) válida por 15 minutos, para aquele único pacote, aceita apenas para enviar e ler o status de uma versão. A CLI faz o upload com ela.
  5. O registro grava a proveniência da execução na nova versão. Ela nunca muda depois disso.

Não existe nada de longa duração para vazar: nenhum token nos secrets da CI, nada para rotacionar. O mesmo token OIDC não pode ser trocado duas vezes, e toda troca é registrada no log de auditoria do registro.

Adicionar um publicador confiável

No painel do publicador, abra o pacote, depois Trusted publishing, e adicione um. Você precisa ser um owner do publicador do pacote. O pacote não precisa existir ainda: um publicador confiável para um novo id de pacote fica guardado no seu publicador, então até a primeira versão pode vir da CI. Para um id de pacote que nunca foi enviado, use Set up a new package na aba Packages do publicador.

CampoNo GitHub ActionsNo GitLab CI
Provedorgithubgitlab
Repositórioowner/repoo caminho do projeto, group/subgroup/project
Workflowo arquivo de workflow da execução, em .github/workflows (publish.yml; o caminho completo também funciona)o caminho no repositório do arquivo de configuração da CI, .gitlab-ci.yml por padrão
Ambiente (opcional)um ambiente de deployment do GitHub que o job precisa usarum ambiente do GitLab protegido que o job precisa usar
Ref (opcional)a branch ou tag da qual a execução deve vir: main (lido como refs/heads/main), refs/tags/v1.2.0, ou um prefixo com um * no final, como refs/tags/v*o mesmo, e a branch ou tag precisa ser protegida no GitLab
  • O workflow é o arquivo da própria execução (workflow_ref de nível superior do GitHub). Quando uma action ou workflow reutilizável faz a publicação, nomeie seu workflow que o chama, como .github/workflows/release.yml.
  • Apenas execuções cujo ref é uma branch ou uma tag (refs/heads/…, refs/tags/…) podem publicar; um ref de pull request (refs/pull/…) nunca pode. O registro recusa execuções de pull_request_target (elas rodam com o ref da branch base em nome do pull request de um fork). workflow_run é permitido: não deixe um workflow iniciado por ele publicar código de um pull request.
  • Quando você o adiciona, o registro consulta o repositório e fixa seus ids numéricos de repositório e de owner. Um repositório excluído e recriado com o mesmo nome tem novos ids e não pode publicar: adicione o publicador confiável novamente se você recriar um repositório de propósito.
  • Um pacote tem no máximo 10 publicadores confiáveis.

Qual CLI

O Trusted Publishing exige uma CLI gamedev mais nova que a 0.32.0; a 0.32.0 e anteriores não conseguem. Fixe uma versão exata na CI em vez de latest, para que uma build de release nunca mude debaixo de você. Até a próxima versão estável, a CLI com Trusted Publishing está no canal beta, então os exemplos aqui usam @baizor/gamedev@beta; eles passam para latest com essa versão. O gamedev pkg publish escolhe sua credencial nesta ordem:

  1. um token de publicador (--token ou AI_GAME_DEV_PUBLISHER_TOKEN), quando informado;
  2. o token OIDC da CI, quando roda no GitHub Actions ou no GitLab CI;
  3. sua sessão autenticada.

Dentro do GitHub Actions, ou em um job do GitLab com AIGD_ID_TOKEN, uma configuração OIDC ausente gera um erro que indica a linha a adicionar; a sessão não é tentada ali. Com --json, o campo auth do resultado informa qual credencial foi usada: oidc-github ou oidc-gitlab para Trusted Publishing. A audience do token deve ser exatamente a do registro: ai-game.dev para produção e, para outro registro, a CLI deriva o nome do host. --oidc-audience <aud> (ou AIGD_OIDC_AUDIENCE) substitui isso; no GitLab, a audience é o aud que o job declara, e a CLI apenas o verifica.

Publicar a partir do GitHub Actions

O job precisa de permissions: id-token: write; é isso que permite solicitar um token com a audience ai-game.dev.

name: Publish package
on:
  push:
    tags: ["v*"]

jobs:
  publish:
    runs-on: ubuntu-latest
    environment: registry            # the trusted publisher requires it (reviewers, branch rules)
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci --ignore-scripts && npm run build   # whatever builds dist/; see the tip below
      - run: npx --yes @baizor/gamedev@beta pkg publish . --notes RELEASE_NOTES.md   # pin an exact version newer than 0.32.0

Salve-o como o arquivo de workflow que você indicou no trusted publisher. O painel do publisher mostra o mesmo snippet com os valores do seu pacote preenchidos.

A action de publicação. Os mesmos passos estão em uma action pronta, IvanMurzak/gamedev-publish-action:

      - run: npm ci --ignore-scripts && npm run build
      - id: publish
        uses: IvanMurzak/gamedev-publish-action@v1
        with:
          path: .
          notes: RELEASE_NOTES.md        # optional; default: the version's section of CHANGELOG.md
          cli-version: beta              # pin an exact version newer than 0.32.0
EntradaPadrãoO que faz
path.A pasta do pacote (com aigd-package.json)
notesvazioUm arquivo Markdown com as notas de release desta versão
waittrueAguarda as verificações do registro e falha o step em caso de rejeição (verificações ainda em andamento quando a espera termina não o fazem falhar); false retorna após o upload
cli-versionlatestA versão de @baizor/gamedev, uma versão exata (recomendado) ou uma dist-tag
audiencevazioA audience OIDC, apenas para um registro diferente do de produção
node-version22O Node.js que executa a CLI

Sua saída result é a saída JSON da CLI: em um upload, id, versão, estado, integridade, auth e (quando houve espera) o relatório de verificações; vazia quando a execução falhou antes do upload.

Para manter cada linha da sua CI no seu próprio repositório, copie o action.yml da action para .github/actions/publish-package/ e use uses: ./.github/actions/publish-package em vez disso; fixe a action em um SHA de commit se você a referenciar a partir do GitHub.

Publicar a partir do GitLab CI

O job declara um ID token chamado AIGD_ID_TOKEN com a audience ai-game.dev, uma única string simples, não uma lista. O GitLab o coloca no ambiente do job, de onde a CLI o lê. O GitLab o emite quando o job começa, e o registro aceita um ID token por uma hora após a emissão: um job que publica mais de uma hora depois de começar falha com OIDC_TOKEN_TOO_OLD, então publique em um job curto e separado.

publish-package:
  image: node:22
  id_tokens:
    AIGD_ID_TOKEN:
      aud: ai-game.dev                 # one audience, a plain string
  environment: registry                # the trusted publisher requires it
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - npm ci --ignore-scripts && npm run build   # whatever builds dist/
    - npx --yes @baizor/gamedev@beta pkg publish .   # pin an exact version newer than 0.32.0

Este job fica no arquivo de configuração de CI que você indicou no trusted publisher (.gitlab-ci.yml por padrão). Proteja o environment registry e suas tags de release no GitLab: o registro recusa um environment ou uma ref fixada que não esteja protegido. O GitLab.com é suportado.

Um template. O mesmo repositório contém um template de GitLab CI com um job oculto, .aigd-publish-package. Inclua-o e estenda o job:

include:
  - remote: https://raw.githubusercontent.com/IvanMurzak/gamedev-publish-action/v1/gitlab/publish-package.gitlab-ci.yml

publish-package:
  extends: .aigd-publish-package
  before_script:
    - npm ci --ignore-scripts && npm run build
  variables:
    AIGD_PACKAGE_PATH: "."
    AIGD_RELEASE_NOTES: ""             # optional Markdown file
    AIGD_CLI_VERSION: beta             # pin an exact version newer than 0.32.0
  environment: registry
  rules:
    - if: $CI_COMMIT_TAG

Você também pode copiar o template para o seu projeto (por exemplo, como ci/publish-package.gitlab-ci.yml) e incluí-lo com local: em vez disso.

Quando uma execução é recusada

publish imprime o motivo do registro e o que o trusted publisher precisa corresponder, não faz upload de nada e sai com código 1. Um job sem id-token: write ou a entrada id_tokens, e sem um token de publisher, recebe a indicação da linha a adicionar. A credencial de upload dura 15 minutos: se as verificações demorarem mais, o step termina sem o veredito delas; leia-o no painel do publisher ou com gamedev pkg publish a partir de uma nova execução de CI ou do seu computador conectado (ele nunca faz upload da mesma versão duas vezes; o mesmo token de CI não pode ser usado duas vezes).

O que o registro verifica

  • O token: emitido por https://token.actions.githubusercontent.com ou https://gitlab.com, assinado com as chaves atuais do provedor, audience exatamente ai-game.dev, dentro do seu período de validade (uma pequena diferença de relógio é permitida), nunca visto antes. Ele precisa ter sido emitido menos de uma hora antes da troca.
  • A correspondência: os ids fixados do repositório e do proprietário, o arquivo de workflow (a ref de workflow de nível superior do GitHub, a ref de configuração de CI do GitLab), uma execução de branch ou tag, e o environment e a ref quando o trusted publisher os define.
  • O upload: a credencial vale para o seu único pacote e expira após 15 minutos. A versão ainda passa por todas as verificações automáticas como qualquer outro upload.

Uma divergência é recusada, e a CLI informa isso (veja acima). Verifique o repositório, o arquivo de workflow e o environment ou a ref usados pela execução.

Procedência

Uma versão publicada via Trusted Publishing registra de onde veio:

CampoExemplo
providergithub
repository, repositoryIdacme/level-tools, seu id numérico
commit, refo SHA do commit e a ref git da execução
workflow.github/workflows/publish.yml
runId, runUrla execução de CI e um link para ela
environmentquando o job usou um

A proveniência vem do token verificado, nunca do pacote, e é imutável. O índice comunitário assinado carrega o provedor, o repositório, o commit, o workflow e o link da execução de cada versão, e o app mostra onde tal versão foi compilada (por exemplo, "built on GitHub Actions", com o repositório, o commit, o workflow e um link para a execução), para que os usuários possam rastrear um pacote até o commit exato e a execução de CI que o compilou.

Tokens de publicador como alternativa

Onde o Trusted Publishing não estiver disponível (outra CI, um GitLab auto-hospedado, um script no seu computador), use um token de publicador:

gamedev pkg publisher token create acme --label ci --days 90
# in CI, with the token stored as a secret:
AI_GAME_DEV_PUBLISHER_TOKEN=$AIGD_PUBLISHER_TOKEN gamedev pkg publish .

Um token (agd_pub_…) pertence a um publicador, é exibido uma única vez, expira após no máximo 365 dias e só pode enviar, ler o status de uma versão e remover. Um publicador tem no máximo 10 tokens ativos; revogue um com gamedev pkg publisher token revoke acme <token id> ou no painel do publicador. Versões enviadas com um token não carregam proveniência.