# Publicación de confianza — App y CLI de AI Game Dev · AI Game Developer Wiki

Publica paquetes de AI Game Dev desde GitHub Actions o GitLab CI sin token: configura un publicador de confianza y la procedencia.

Esta página se tradujo automáticamente del inglés. [Lee el original en inglés](https://ai-game.dev/docs/wiki/app/trusted-publishing).

La publicación de confianza permite que un trabajo de CI publique tu paquete sin ningún secreto almacenado en la CI: GitHub Actions o GitLab CI responde por qué repositorio y flujo de trabajo se está ejecutando, y ai-game.dev canjea esa prueba por una credencial de corta duración que puede subir un paquete. Cada versión publicada de esta forma registra su **procedencia**: el repositorio, el commit y la ejecución de CI con la que se construyó. Esta página muestra cómo configurarla para GitHub y GitLab, y qué se comprueba.

## Cómo funciona

1. Indicas al registro qué repositorio y flujo de trabajo pueden publicar un paquete: un **publicador de confianza**.
2. Tu trabajo de CI ejecuta `gamedev pkg publish` sin token de publicador. La CLI detecta que se ejecuta en GitHub Actions (`ACTIONS_ID_TOKEN_REQUEST_URL`) o en GitLab CI (`AIGD_ID_TOKEN`) y pide a la CI un token de identidad OIDC con la audiencia `ai-game.dev`.
3. La CLI envía ese token a `POST /api/registry/v1/oidc/token`. El registro lo verifica (emisor, firma, audiencia `ai-game.dev`, caducidad) y lo compara con los publicadores de confianza del paquete.
4. Si coincide, devuelve una credencial (`agd_oidc_…`) válida durante **15 minutos**, para **ese único paquete**, aceptada solo para subir y leer el estado de una versión. La CLI sube con ella.
5. El registro anota la procedencia de la ejecución en la nueva versión. Nunca cambia después.

No existe nada de larga duración que pueda filtrarse: ni un token en los secretos de CI, nada que rotar. El mismo token OIDC no se puede canjear dos veces, y cada canje queda registrado en el registro de auditoría del registro.

## Añadir un publicador de confianza

En el [panel del publicador](https://ai-game.dev/publisher), abre el paquete, ve a **Trusted publishing** y añade uno. Debes ser **owner** del publicador del paquete. El paquete no tiene por qué existir todavía: un publicador de confianza para un id de paquete nuevo se conserva para tu publicador, así que incluso la primera versión puede venir de la CI. Para un id de paquete que nunca se ha subido, usa **Set up a new package** en la pestaña Packages del publicador.

| Campo | En GitHub Actions | En GitLab CI |
| --- | --- | --- |
| Proveedor | `github` | `gitlab` |
| Repositorio | `owner/repo` | la ruta del proyecto, `group/subgroup/project` |
| Flujo de trabajo | el archivo de flujo de trabajo de la ejecución, en `.github/workflows` (`publish.yml`; también sirve la ruta completa) | la ruta en el repositorio del archivo de configuración de CI, `.gitlab-ci.yml` de forma predeterminada |
| Entorno (opcional) | un entorno de despliegue de GitHub que el trabajo debe usar | un entorno de GitLab **protegido** que el trabajo debe usar |
| Ref (opcional) | la rama o etiqueta de la que debe provenir la ejecución: `main` (se interpreta como `refs/heads/main`), `refs/tags/v1.2.0`, o un prefijo con un `*` final, como `refs/tags/v*` | lo mismo, y la rama o etiqueta debe estar **protegida** en GitLab |

- El flujo de trabajo es el archivo de la propia ejecución (el `workflow_ref` de nivel superior de GitHub). Cuando la publicación la hace una acción o un flujo de trabajo reutilizable, indica **tu** flujo de trabajo que lo llama, como `.github/workflows/release.yml`.
- Solo pueden publicar las ejecuciones cuyo ref sea una rama o una etiqueta (`refs/heads/…`, `refs/tags/…`); un ref de pull request (`refs/pull/…`) nunca puede. El registro rechaza las ejecuciones de `pull_request_target` (se ejecutan con el ref de la rama base en nombre del pull request de un fork). `workflow_run` está permitido: no dejes que un flujo de trabajo que inicie publique código de un pull request.
- Cuando lo añades, el registro busca el repositorio y fija sus ids numéricos de repositorio y de propietario. Un repositorio eliminado y creado de nuevo con el mismo nombre tiene ids nuevos y no puede publicar: vuelve a añadir el publicador de confianza si recreas un repositorio a propósito.
- Un paquete tiene como máximo 10 publicadores de confianza.

**Advertencia**

El flujo de trabajo se compara por su ruta, no por su contenido: cualquiera que pueda hacer push a una rama puede editar ese archivo. En GitHub, configura un entorno con revisores obligatorios o una regla de rama de despliegue en cada publicador de confianza; un ref por sí solo protege únicamente cuando esa rama está protegida o las etiquetas están cubiertas por un conjunto de reglas de etiquetas (de lo contrario, cualquiera con acceso de escritura puede hacer push a una etiqueta como `v9.9.9` sobre un flujo de trabajo editado). En GitLab el propio registro exige que un entorno fijado y un ref fijado estén protegidos.

## Qué CLI usar

La publicación de confianza necesita una CLI `gamedev` posterior a 0.32.0; 0.32.0 y anteriores no pueden hacerlo. Fija una versión exacta en la CI en lugar de `latest`, para que una compilación de publicación nunca cambie bajo tus pies. Hasta la próxima versión estable, la CLI con publicación de confianza está en el canal `beta`, así que los ejemplos usan `@baizor/gamedev@beta`; pasarán a `latest` con esa versión. `gamedev pkg publish` elige su credencial en este orden:

1. un token de publicador (`--token` o `AI_GAME_DEV_PUBLISHER_TOKEN`), cuando se proporciona;
2. el token OIDC de la CI, cuando se ejecuta en GitHub Actions o GitLab CI;
3. tu sesión iniciada.

Dentro de GitHub Actions, o en un job de GitLab con `AIGD_ID_TOKEN`, una configuración de OIDC ausente es un error que indica la línea que hay que añadir; allí no se intenta la sesión. Con `--json`, el campo `auth` del resultado indica la credencial que se usó: `oidc-github` u `oidc-gitlab` para Trusted Publishing. La audiencia del token debe ser exactamente la del registro: `ai-game.dev` para producción, y para otro registro la CLI deriva su nombre de host. `--oidc-audience <aud>` (o `AIGD_OIDC_AUDIENCE`) lo sobrescribe; en GitLab la audiencia es el `aud` que declara el job, y la CLI solo lo comprueba.

## Publicar desde GitHub Actions

El job necesita `permissions: id-token: write`; eso es lo que le permite solicitar un token con la audiencia `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
```

Guárdalo como el archivo de workflow que indicaste en el publicador de confianza. El panel del publicador muestra el mismo fragmento con los valores de tu paquete rellenados.

**Consejo**

Todos los pasos de un job que pueda solicitar el token pueden usarlo, incluidos los scripts de instalación de tus dependencias. Instala con `npm ci --ignore-scripts` cuando tu compilación lo permita, o compila en un job aparte sin `id-token: write` y pasa `dist/` como artefacto.

**La acción de publicación.** Los mismos pasos son una acción lista para usar, [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 | Predeterminado | Qué hace |
| --- | --- | --- |
| `path` | `.` | La carpeta del paquete (con `aigd-package.json`) |
| `notes` | vacío | Un archivo Markdown con las notas de publicación de esta versión |
| `wait` | `true` | Espera a las comprobaciones del registro y hace fallar el paso si hay un rechazo (las comprobaciones que sigan en curso cuando termine la espera no lo hacen fallar); `false` vuelve tras la subida |
| `cli-version` | `latest` | La versión de `@baizor/gamedev`, una versión exacta (recomendado) o un dist-tag |
| `audience` | vacío | La audiencia de OIDC, solo para un registro distinto del de producción |
| `node-version` | `22` | La versión de Node.js que ejecuta la CLI |

Su salida `result` es la salida JSON de la CLI: en una subida, id, versión, estado, integridad, auth y (cuando esperó) el informe de comprobaciones; vacía cuando la ejecución falló antes de subir.

Para mantener cada línea de tu CI en tu propio repositorio, copia el `action.yml` de la acción en `.github/actions/publish-package/` y usa `uses: ./.github/actions/publish-package` en su lugar; fija la acción a un SHA de commit si la referencias desde GitHub.

## Publicar desde GitLab CI

El job declara un token de ID llamado `AIGD_ID_TOKEN` con la audiencia `ai-game.dev`, una cadena simple, no una lista. GitLab lo pone en el entorno del job, donde la CLI lo lee. GitLab lo emite cuando empieza el job, y el registro acepta un token de ID durante una hora desde su emisión: un job que publica más de una hora después de empezar falla con `OIDC_TOKEN_TOO_OLD`, así que publica en un job corto y propio.

```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 vive en el archivo de configuración de CI que indicaste en el publicador de confianza (`.gitlab-ci.yml` por defecto). Protege el entorno `registry` y tus tags de release en GitLab: el registro rechaza un entorno o una ref fijados que no estén protegidos. GitLab.com es compatible.

**Una plantilla.** El mismo repositorio contiene una plantilla de GitLab CI con un job oculto, `.aigd-publish-package`. Inclúyela y extiende el 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
```

También puedes copiar la plantilla en tu proyecto (por ejemplo como `ci/publish-package.gitlab-ci.yml`) e incluirla con `local:` en su lugar.

## Cuando se rechaza una ejecución

`publish` imprime el motivo del registro y con qué debe coincidir el publicador de confianza, no sube nada y sale con 1. A un job sin `id-token: write` ni la entrada `id_tokens`, y sin un token de publicador, se le indica qué línea añadir. La credencial de subida dura 15 minutos: si las comprobaciones tardan más, el paso termina sin su veredicto; léelo en el panel del publicador, o con `gamedev pkg publish` desde una nueva ejecución de CI o tu ordenador con sesión iniciada (nunca sube la misma versión dos veces; el mismo token de CI no se puede usar dos veces).

## Qué comprueba el registro

- **El token:** emitido por `https://token.actions.githubusercontent.com` o `https://gitlab.com`, firmado con las claves actuales del proveedor, con audiencia exactamente `ai-game.dev`, dentro de su periodo de validez (se permite una pequeña desviación de reloj), y que no se haya visto antes. Debe haberse emitido menos de una hora antes del intercambio.
- **La coincidencia:** los ids fijados del repositorio y del propietario, el archivo de workflow (la ref de workflow de nivel superior de GitHub, la ref de configuración de CI de GitLab), una ejecución de rama o tag, y el entorno y la ref cuando el publicador de confianza los establece.
- **La subida:** la credencial funciona para su único paquete y caduca a los 15 minutos. La versión sigue pasando todas las [comprobaciones automáticas](https://ai-game.dev/es/docs/wiki/app/package-registry#checks) como cualquier otra subida.

Una falta de coincidencia se rechaza, y la CLI lo indica (ver [arriba](https://ai-game.dev/es/docs/wiki/app/trusted-publishing#refused)). Revisa el repositorio, el archivo de workflow y el entorno o la ref que usó la ejecución.

## Procedencia

Una versión publicada mediante Trusted Publishing registra de dónde vino:

| Campo | Ejemplo |
| --- | --- |
| `provider` | `github` |
| `repository`, `repositoryId` | `acme/level-tools`, su id numérico |
| `commit`, `ref` | el SHA del commit y la ref de git de la ejecución |
| `workflow` | `.github/workflows/publish.yml` |
| `runId`, `runUrl` | la ejecución de CI y un enlace a ella |
| `environment` | cuando el trabajo usó uno |

La procedencia proviene del token verificado, nunca del paquete, y es inmutable. El índice comunitario firmado incluye el proveedor, el repositorio, el commit, el flujo de trabajo y el enlace a la ejecución de cada versión, y la aplicación muestra dónde se compiló dicha versión (por ejemplo, «compilada en GitHub Actions», con el repositorio, el commit, el flujo de trabajo y un enlace a la ejecución), de modo que los usuarios pueden seguir un paquete hasta el commit exacto y la ejecución de CI que lo compiló.

## En su lugar, tokens de publicador

Cuando Trusted Publishing no está disponible (otro CI, un GitLab autoalojado, un script en tu ordenador), usa un 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 .
```

Un token (`agd_pub_…`) pertenece a un único publicador, se muestra una sola vez, caduca tras un máximo de 365 días y solo puede subir, leer el estado de una versión y retirar. Un publicador tiene como máximo 10 tokens activos; revoca uno con `gamedev pkg publisher token revoke acme <token id>` o en el panel del publicador. Las versiones subidas con un token no llevan procedencia.

## Páginas relacionadas

- [Publicar paquetes](https://ai-game.dev/es/docs/wiki/app/publishing-packages) para las notas de la versión, los canales y la deprecación.
- [Reglas y comprobaciones del registro](https://ai-game.dev/es/docs/wiki/app/package-registry) para las comprobaciones que supera cada versión.

---

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

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