Trusted Publishing
AI Game Dev-Pakete aus GitHub Actions oder GitLab CI ohne Token veröffentlichen: Trusted Publisher, Workflows und Provenance einrichten.
Mit Trusted Publishing kann ein CI-Job dein Paket veröffentlichen, ohne dass ein Secret in der CI gespeichert ist: GitHub Actions oder GitLab CI verbürgen sich dafür, welches Repository und welcher Workflow läuft, und ai-game.dev tauscht diesen Nachweis gegen ein kurzlebiges Credential ein, das ein Paket hochladen kann. Jede so veröffentlichte Version zeichnet ihre Provenance auf: das Repository, den Commit und den CI-Lauf, aus dem sie gebaut wurde. Diese Seite zeigt, wie du das für GitHub und GitLab einrichtest und was geprüft wird.
So funktioniert es
- Du teilst der Registry mit, welches Repository und welcher Workflow ein Paket veröffentlichen darf: ein Trusted Publisher.
- Dein CI-Job führt
gamedev pkg publishohne Publisher-Token aus. Die CLI erkennt, dass sie in GitHub Actions (ACTIONS_ID_TOKEN_REQUEST_URL) oder GitLab CI (AIGD_ID_TOKEN) läuft, und fordert von der CI ein OIDC-Identitätstoken mit der Audienceai-game.devan. - Die CLI sendet dieses Token an
POST /api/registry/v1/oidc/token. Die Registry verifiziert es (Issuer, Signatur, Audienceai-game.dev, Ablauf) und gleicht es mit den Trusted Publishern des Pakets ab. - Bei einem Treffer gibt sie ein Credential (
agd_oidc_…) zurück, das 15 Minuten lang gültig ist, nur für dieses eine Paket gilt und ausschließlich zum Hochladen und zum Abrufen des Status einer Version akzeptiert wird. Die CLI lädt damit hoch. - Die Registry zeichnet die Provenance des Laufs an der neuen Version auf. Sie ändert sich danach nie mehr.
Es existiert nichts Langlebiges, das leaken könnte: kein Token in CI-Secrets, nichts zu rotieren. Dasselbe OIDC-Token kann nicht zweimal eingetauscht werden, und jeder Tausch wird im Audit-Log der Registry festgehalten.
Einen Trusted Publisher hinzufügen
Öffne im Publisher-Panel das Paket, dann Trusted publishing, und füge einen hinzu. Du musst owner des Publishers des Pakets sein. Das Paket muss noch nicht existieren: Ein Trusted Publisher für eine neue Paket-ID wird für deinen Publisher gespeichert, sodass sogar die erste Version aus der CI kommen kann. Für eine Paket-ID, die noch nie hochgeladen wurde, nutze Set up a new package im Tab Packages des Publishers.
| Feld | In GitHub Actions | In GitLab CI |
|---|---|---|
| Provider | github | gitlab |
| Repository | owner/repo | der Projektpfad, group/subgroup/project |
| Workflow | die Workflow-Datei des Laufs, in .github/workflows (publish.yml; der vollständige Pfad funktioniert auch) | der Repository-Pfad der CI-Konfigurationsdatei, standardmäßig .gitlab-ci.yml |
| Environment (optional) | eine GitHub-Deployment-Umgebung, die der Job verwenden muss | eine protected GitLab-Umgebung, die der Job verwenden muss |
| Ref (optional) | der Branch oder Tag, aus dem der Lauf kommen muss: main (gelesen als refs/heads/main), refs/tags/v1.2.0 oder ein Präfix mit einem abschließenden *, etwa refs/tags/v* | dasselbe, und der Branch oder Tag muss in GitLab protected sein |
- Der Workflow ist die Datei des Laufs selbst (GitHubs oberste
workflow_ref). Wenn eine wiederverwendbare Action oder ein wiederverwendbarer Workflow das Veröffentlichen übernimmt, gib deinen Workflow an, der sie aufruft, etwa.github/workflows/release.yml. - Nur Läufe, deren Ref ein Branch oder ein Tag ist (
refs/heads/…,refs/tags/…), können veröffentlichen; ein Pull-Request-Ref (refs/pull/…) kann es nie. Die Registry lehntpull_request_target-Läufe ab (sie laufen mit dem Ref des Basis-Branches im Auftrag des Pull Requests eines Forks).workflow_runist erlaubt: Lass einen davon gestarteten Workflow keinen Code aus einem Pull Request veröffentlichen. - Beim Hinzufügen schlägt die Registry das Repository nach und pinnt dessen numerische Repository- und Owner-IDs. Ein gelöschtes und unter demselben Namen neu erstelltes Repository hat neue IDs und kann nicht veröffentlichen: Füge den Trusted Publisher erneut hinzu, wenn du ein Repository absichtlich neu erstellst.
- Ein Paket hat höchstens 10 Trusted Publisher.
Welche CLI
Trusted Publishing benötigt eine gamedev-CLI neuer als 0.32.0; 0.32.0 und älter können es nicht. Pinne in der CI eine exakte Version statt latest, damit sich ein Release-Build nie unter dir ändert. Bis zum nächsten stabilen Release liegt die CLI mit Trusted Publishing im Channel beta, daher verwenden die Beispiele hier @baizor/gamedev@beta; mit diesem Release wechseln sie zu latest. gamedev pkg publish wählt sein Credential in dieser Reihenfolge:
- ein Publisher-Token (
--tokenoderAI_GAME_DEV_PUBLISHER_TOKEN), wenn eines angegeben ist; - das OIDC-Token der CI, wenn sie in GitHub Actions oder GitLab CI läuft;
- deine angemeldete Sitzung.
In GitHub Actions oder in einem GitLab-Job mit AIGD_ID_TOKEN ist ein fehlendes OIDC-Setup ein Fehler, der die hinzuzufügende Zeile nennt; dort wird die Sitzung nicht versucht. Mit --json nennt das Feld auth des Ergebnisses die verwendete Anmeldeinformation: oidc-github oder oidc-gitlab für Trusted Publishing. Die Audience des Tokens muss genau der der Registry entsprechen: ai-game.dev für die Produktion, und für eine andere Registry leitet die CLI deren Hostnamen ab. --oidc-audience <aud> (oder AIGD_OIDC_AUDIENCE) überschreibt das; auf GitLab ist die Audience der aud, den der Job deklariert, und die CLI prüft ihn nur.
Aus GitHub Actions veröffentlichen
Der Job braucht permissions: id-token: write; nur damit kann er ein Token mit der Audience ai-game.dev anfordern.
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.0Speichere ihn als die Workflow-Datei, die du beim Trusted Publisher angegeben hast. Das Publisher-Panel zeigt denselben Ausschnitt mit den Werten deines Pakets ausgefüllt.
Die Publish-Action. Dieselben Schritte gibt es als fertige Action, 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| Eingabe | Standard | Was sie bewirkt |
|---|---|---|
path | . | Der Paketordner (mit aigd-package.json) |
notes | leer | Eine Markdown-Datei mit den Release Notes dieser Version |
wait | true | Auf die Prüfungen der Registry warten und den Schritt bei einer Ablehnung fehlschlagen lassen (Prüfungen, die beim Ende der Wartezeit noch laufen, lassen ihn nicht fehlschlagen); false kehrt nach dem Upload zurück |
cli-version | latest | Die Version von @baizor/gamedev, eine exakte Version (empfohlen) oder ein dist-tag |
audience | leer | Die OIDC-Audience, nur für eine andere Registry als die Produktion |
node-version | 22 | Die Node.js-Version, die die CLI ausführt |
Seine Ausgabe result ist die JSON-Ausgabe der CLI: bei einem Upload id, version, state, integrity, auth und (wenn gewartet wurde) der Prüfbericht; leer, wenn der Lauf vor dem Upload fehlgeschlagen ist.
Um jede Zeile deiner CI im eigenen Repository zu behalten, kopiere die action.yml der Action nach .github/actions/publish-package/ und verwende stattdessen uses: ./.github/actions/publish-package; pinne die Action auf einen Commit-SHA, wenn du sie von GitHub aus referenzierst.
Aus GitLab CI veröffentlichen
Der Job deklariert ein ID-Token namens AIGD_ID_TOKEN mit der Audience ai-game.dev, einen einfachen String, keine Liste. GitLab legt es in die Umgebung des Jobs, wo die CLI es liest. GitLab stellt es beim Start des Jobs aus, und die Registry akzeptiert ein ID-Token eine Stunde lang nach seiner Ausstellung: Ein Job, der mehr als eine Stunde nach seinem Start veröffentlicht, schlägt mit OIDC_TOKEN_TOO_OLD fehl. Veröffentliche daher in einem kurzen, eigenen Job.
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.0Dieser Job steht in der CI-Konfigurationsdatei, die du beim Trusted Publisher angegeben hast (standardmäßig .gitlab-ci.yml). Schütze die Umgebung registry und deine Release-Tags in GitLab: Die Registry lehnt eine ungeschützte gepinnte Umgebung oder einen ungeschützten Ref ab. GitLab.com wird unterstützt.
Ein Template. Dasselbe Repository enthält ein GitLab-CI-Template mit einem versteckten Job, .aigd-publish-package. Binde es ein und erweitere den 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_TAGDu kannst das Template auch in dein Projekt kopieren (zum Beispiel als ci/publish-package.gitlab-ci.yml) und es stattdessen mit local: einbinden.
Wenn ein Lauf abgelehnt wird
publish gibt den Grund der Registry und die Bedingungen aus, die der Trusted Publisher erfüllen muss, lädt nichts hoch und beendet sich mit 1. Einem Job ohne id-token: write oder den id_tokens-Eintrag und ohne Publisher-Token wird gesagt, welche Zeile hinzuzufügen ist. Die Upload-Anmeldeinformation gilt 15 Minuten: Dauern die Prüfungen länger, endet der Schritt ohne ihr Urteil; lies es im Publisher-Panel oder mit gamedev pkg publish aus einem neuen CI-Lauf oder von deinem angemeldeten Rechner (dieselbe Version wird nie zweimal hochgeladen; dasselbe CI-Token kann nicht zweimal verwendet werden).
Was die Registry prüft
- Das Token: ausgestellt von
https://token.actions.githubusercontent.comoderhttps://gitlab.com, signiert mit den aktuellen Schlüsseln des Anbieters, Audience exaktai-game.dev, innerhalb seiner Gültigkeitsdauer (eine kleine Uhrabweichung ist erlaubt), noch nie zuvor gesehen. Es muss weniger als eine Stunde vor dem Austausch ausgestellt worden sein. - Die Übereinstimmung: die gepinnten Repository- und Owner-IDs, die Workflow-Datei (bei GitHub der Ref des Workflows auf oberster Ebene, bei GitLab der Ref der CI-Konfiguration), ein Branch- oder Tag-Lauf sowie Umgebung und Ref, wenn der Trusted Publisher sie festlegt.
- Der Upload: die Anmeldeinformation gilt nur für ihr eines Paket und läuft nach 15 Minuten ab. Die Version durchläuft weiterhin jede automatische Prüfung wie jeder andere Upload.
Eine Abweichung wird abgelehnt, und die CLI sagt das auch (siehe oben). Prüfe das Repository, die Workflow-Datei und die Umgebung bzw. den Ref, den der Lauf verwendet hat.
Herkunft
Eine über Trusted Publishing veröffentlichte Version hält fest, woher sie stammt:
| Feld | Beispiel |
|---|---|
provider | github |
repository, repositoryId | acme/level-tools, seine numerische ID |
commit, ref | der Commit-SHA und der Git-Ref des Laufs |
workflow | .github/workflows/publish.yml |
runId, runUrl | der CI-Lauf und ein Link dazu |
environment | falls der Job eine verwendet hat |
Die Provenienz stammt aus dem verifizierten Token, nie aus dem Paket, und ist unveränderlich. Der signierte Community-Index enthält für jede Version den Provider, das Repository, den Commit, den Workflow und den Link zum Lauf, und die App zeigt an, wo eine solche Version gebaut wurde (zum Beispiel "built on GitHub Actions", mit Repository, Commit, Workflow und einem Link zum Lauf), sodass Nutzer ein Paket bis zum exakten Commit und CI-Lauf zurückverfolgen können, der es gebaut hat.
Alternativ Publisher-Tokens
Wo Trusted Publishing nicht verfügbar ist (eine andere CI, ein selbst gehostetes GitLab, ein Skript auf deinem Rechner), verwende ein Publisher-Token:
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 .Ein Token (agd_pub_…) gehört zu genau einem Publisher, wird nur einmal angezeigt, läuft nach höchstens 365 Tagen ab und kann ausschließlich hochladen, den Status einer Version lesen und yank ausführen. Ein Publisher hat höchstens 10 aktive Tokens; widerrufe eines mit gamedev pkg publisher token revoke acme <token id> oder im Publisher-Panel. Mit einem Token hochgeladene Versionen tragen keine Provenienz.
Verwandte Seiten
- Publishing packages für Release Notes, Channels und Deprecation.
- Registry rules and checks für die Prüfungen, die jede Version durchläuft.