Publicación de confianza
Publica paquetes de AI Game Dev desde GitHub Actions o GitLab CI sin token: configura un publicador de confianza y la procedencia.
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
- Indicas al registro qué repositorio y flujo de trabajo pueden publicar un paquete: un publicador de confianza.
- Tu trabajo de CI ejecuta
gamedev pkg publishsin 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 audienciaai-game.dev. - La CLI envía ese token a
POST /api/registry/v1/oidc/token. El registro lo verifica (emisor, firma, audienciaai-game.dev, caducidad) y lo compara con los publicadores de confianza del paquete. - 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. - 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, 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_refde 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 depull_request_target(se ejecutan con el ref de la rama base en nombre del pull request de un fork).workflow_runestá 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.
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:
- un token de publicador (
--tokenoAI_GAME_DEV_PUBLISHER_TOKEN), cuando se proporciona; - el token OIDC de la CI, cuando se ejecuta en GitHub Actions o GitLab CI;
- 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.
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.0Guá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.
La acción de publicación. Los mismos pasos son una acción lista para usar, 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 | 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.
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 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:
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_TAGTambié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.comohttps://gitlab.com, firmado con las claves actuales del proveedor, con audiencia exactamenteai-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 como cualquier otra subida.
Una falta de coincidencia se rechaza, y la CLI lo indica (ver arriba). 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:
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 para las notas de la versión, los canales y la deprecación.
- Reglas y comprobaciones del registro para las comprobaciones que supera cada versión.