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.
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
- Você informa ao registro qual repositório e workflow podem publicar um pacote: um publicador confiável.
- Seu job de CI executa
gamedev pkg publishsem 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 audienceai-game.dev. - A CLI envia esse token para
POST /api/registry/v1/oidc/token. O registro o verifica (emissor, assinatura, audienceai-game.dev, validade) e o compara com os publicadores confiáveis do pacote. - 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. - 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.
| Campo | No GitHub Actions | No GitLab CI |
|---|---|---|
| Provedor | github | gitlab |
| Repositório | owner/repo | o caminho do projeto, group/subgroup/project |
| Workflow | o 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 usar | um 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_refde 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 depull_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:
- um token de publicador (
--tokenouAI_GAME_DEV_PUBLISHER_TOKEN), quando informado; - o token OIDC da CI, quando roda no GitHub Actions ou no GitLab CI;
- 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.0Salve-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| Entrada | Padrão | O que faz |
|---|---|---|
path | . | A pasta do pacote (com aigd-package.json) |
notes | vazio | Um arquivo Markdown com as notas de release desta versão |
wait | true | Aguarda 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-version | latest | A versão de @baizor/gamedev, uma versão exata (recomendado) ou uma dist-tag |
audience | vazio | A audience OIDC, apenas para um registro diferente do de produção |
node-version | 22 | O 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.0Este 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_TAGVocê 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.comouhttps://gitlab.com, assinado com as chaves atuais do provedor, audience exatamenteai-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:
| Campo | Exemplo |
|---|---|
provider | github |
repository, repositoryId | acme/level-tools, seu id numérico |
commit, ref | o SHA do commit e a ref git da execução |
workflow | .github/workflows/publish.yml |
runId, runUrl | a execução de CI e um link para ela |
environment | quando 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.
Páginas relacionadas
- Publicando pacotes para notas de versão, canais e descontinuação.
- Regras e verificações do registro para as verificações que cada versão passa.