# Publicação Confiável — App e CLI do AI Game Dev · AI Game Developer Wiki

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.

Esta página foi traduzida automaticamente do inglês. [Leia o original em inglês](https://ai-game.dev/docs/wiki/app/trusted-publishing).

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](https://ai-game.dev/publisher), 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_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.

**Aviso**

O workflow é comparado pelo caminho, não pelo conteúdo: qualquer pessoa que possa fazer push em uma branch pode editar esse arquivo. No GitHub, defina um ambiente com revisores obrigatórios ou uma regra de branch de deployment em cada publicador confiável; um ref sozinho só protege quando essa branch é protegida ou as tags são cobertas por um ruleset de tags (caso contrário, qualquer pessoa com acesso de escrita pode fazer push de uma tag como `v9.9.9` em um workflow editado). No GitLab, o próprio registro exige que um ambiente fixado e um ref fixado sejam protegidos.

## 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`.

```yaml
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.

**Dica**

Todo step de um job que possa solicitar o token pode usá-lo, incluindo scripts de instalação das suas dependências. Instale com `npm ci --ignore-scripts` onde seu build permitir, ou faça o build em um job separado sem `id-token: write` e passe `dist/` adiante como artefato.

**A action de publicação.** Os mesmos passos estão em uma action pronta, [IvanMurzak/gamedev-publish-action](https://github.com/IvanMurzak/gamedev-publish-action):

```yaml
      - 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.

```yaml
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:

```yaml
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](https://ai-game.dev/pt-br/docs/wiki/app/package-registry#checks) como qualquer outro upload.

Uma divergência é recusada, e a CLI informa isso (veja [acima](https://ai-game.dev/pt-br/docs/wiki/app/trusted-publishing#refused)). 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:

```bash
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](https://ai-game.dev/pt-br/docs/wiki/app/publishing-packages) para notas de versão, canais e descontinuação.
- [Regras e verificações do registro](https://ai-game.dev/pt-br/docs/wiki/app/package-registry) para as verificações que cada versão passa.

---

Source (HTML): https://ai-game.dev/pt-br/docs/wiki/app/trusted-publishing

Machine-translated (pt-BR) from the English page: https://ai-game.dev/docs/wiki/app/trusted-publishing
