# Trusted Publishing — AI Game Dev App & CLI · AI Game Developer Wiki

AI Game Dev-Pakete aus GitHub Actions oder GitLab CI ohne Token veröffentlichen: Trusted Publisher, Workflows und Provenance einrichten.

Diese Seite wurde maschinell aus dem Englischen übersetzt. [Englisches Original lesen](https://ai-game.dev/docs/wiki/app/trusted-publishing).

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

1. Du teilst der Registry mit, welches Repository und welcher Workflow ein Paket veröffentlichen darf: ein **Trusted Publisher**.
2. Dein CI-Job führt `gamedev pkg publish` ohne 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 Audience `ai-game.dev` an.
3. Die CLI sendet dieses Token an `POST /api/registry/v1/oidc/token`. Die Registry verifiziert es (Issuer, Signatur, Audience `ai-game.dev`, Ablauf) und gleicht es mit den Trusted Publishern des Pakets ab.
4. 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.
5. 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](https://ai-game.dev/publisher) 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 lehnt `pull_request_target`-Läufe ab (sie laufen mit dem Ref des Basis-Branches im Auftrag des Pull Requests eines Forks). `workflow_run` ist 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.

**Warnung**

Der Workflow wird über seinen Pfad abgeglichen, nicht über seinen Inhalt: Wer einen Branch pushen kann, kann diese Datei bearbeiten. Lege auf GitHub für jeden Trusted Publisher ein Environment mit erforderlichen Reviewern oder eine Deployment-Branch-Regel an; ein Ref allein schützt nur, wenn dieser Branch geschützt ist oder die Tags von einem Tag-Ruleset abgedeckt sind (sonst kann jeder mit Schreibzugriff ein Tag wie `v9.9.9` auf einem bearbeiteten Workflow pushen). Auf GitLab verlangt die Registry selbst, dass ein gepinntes Environment und ein gepinnter Ref geschützt sind.

## 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:

1. ein Publisher-Token (`--token` oder `AI_GAME_DEV_PUBLISHER_TOKEN`), wenn eines angegeben ist;
2. das OIDC-Token der CI, wenn sie in GitHub Actions oder GitLab CI läuft;
3. 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.

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

Speichere 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.

**Tipp**

Jeder Schritt eines Jobs, der das Token anfordern darf, kann es verwenden, auch Install-Skripte deiner Abhängigkeiten. Installiere mit `npm ci --ignore-scripts`, wo dein Build es zulässt, oder baue in einem separaten Job ohne `id-token: write` und reiche `dist/` als Artefakt weiter.

**Die Publish-Action.** Dieselben Schritte gibt es als fertige Action, [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
```

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

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

Dieser 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:

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

Du 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.com` oder `https://gitlab.com`, signiert mit den aktuellen Schlüsseln des Anbieters, Audience exakt `ai-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](https://ai-game.dev/de/docs/wiki/app/package-registry#checks) wie jeder andere Upload.

Eine Abweichung wird abgelehnt, und die CLI sagt das auch (siehe [oben](https://ai-game.dev/de/docs/wiki/app/trusted-publishing#refused)). 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:

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

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](https://ai-game.dev/de/docs/wiki/app/publishing-packages) für Release Notes, Channels und Deprecation.
- [Registry rules and checks](https://ai-game.dev/de/docs/wiki/app/package-registry) für die Prüfungen, die jede Version durchläuft.

---

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

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