# トラステッドパブリッシング — AI Game DevアプリとCLI · AI Game Developer Wiki

GitHub Actions や GitLab CI からトークンを保存せずに AI Game Dev パッケージを公開する方法: トラステッドパブリッシャー、ワークフローファイル、provenance の設定。

このページは英語から機械翻訳されています。[英語の原文を読む](https://ai-game.dev/docs/wiki/app/trusted-publishing)。

トラステッドパブリッシングを使うと、CI にシークレットを保存することなく CI ジョブからパッケージを公開できます。GitHub Actions または GitLab CI が、どのリポジトリとワークフローが実行されているかを保証し、ai-game.dev はその証明を、1 つのパッケージをアップロードできる短期間有効な資格情報と引き換えます。この方法で公開されたすべてのバージョンには **provenance** が記録されます。provenance には、どのリポジトリ、コミット、CI 実行からビルドされたかが含まれます。このページでは、GitHub と GitLab での設定方法と、何が検証されるかを説明します。

## 仕組み

1. どのリポジトリとワークフローがパッケージを公開できるかをレジストリに登録します。これが**トラステッドパブリッシャー**です。
2. CI ジョブはパブリッシャートークンなしで `gamedev pkg publish` を実行します。CLI は自分が GitHub Actions (`ACTIONS_ID_TOKEN_REQUEST_URL`) または GitLab CI (`AIGD_ID_TOKEN`) で実行されていることを検知し、オーディエンス `ai-game.dev` で OIDC ID トークンを CI に要求します。
3. CLI はそのトークンを `POST /api/registry/v1/oidc/token` に送信します。レジストリはトークンを検証し (発行者、署名、オーディエンス `ai-game.dev`、有効期限)、パッケージのトラステッドパブリッシャーと照合します。
4. 一致すると、**15 分間**有効で、**その 1 つのパッケージ**専用の資格情報 (`agd_oidc_…`) を返します。これはバージョンのアップロードとステータスの読み取りにのみ使用できます。CLI はこの資格情報でアップロードします。
5. レジストリは新しいバージョンにその実行の provenance を記録します。これは後から変更されることはありません。

漏えいする可能性のある長期間有効なものはありません。CI シークレットにトークンはなく、ローテーションする必要もありません。同じ OIDC トークンを 2 回交換することはできず、すべての交換はレジストリの監査ログに記録されます。

## トラステッドパブリッシャーを追加する

[パブリッシャーパネル](https://ai-game.dev/publisher) でパッケージを開き、**Trusted publishing** を選択して追加します。パッケージのパブリッシャーの**オーナー**である必要があります。パッケージはまだ存在していなくてもかまいません。新しいパッケージ id のトラステッドパブリッシャーはパブリッシャーに保持されるため、最初のバージョンから CI で公開できます。 一度もアップロードされていないパッケージ id には、パブリッシャーの Packages タブで **Set up a new package** を使用します。

| フィールド | GitHub Actions の場合 | GitLab CI の場合 |
| --- | --- | --- |
| プロバイダー | `github` | `gitlab` |
| リポジトリ | `owner/repo` | プロジェクトパス、`group/subgroup/project` |
| ワークフロー | 実行されたワークフローファイル (`.github/workflows` 内の `publish.yml`。フルパスでも可) | CI 設定ファイルのリポジトリ内パス。デフォルトは `.gitlab-ci.yml` |
| 環境 (任意) | ジョブが使用する必要がある GitHub デプロイメント環境 | ジョブが使用する必要がある**保護された** GitLab 環境 |
| Ref (任意) | 実行の元になるブランチまたはタグ: `main` (`refs/heads/main` として解釈)、`refs/tags/v1.2.0`、または末尾に `*` が 1 つ付いたプレフィックス (例: `refs/tags/v*`) | 同上。さらに、ブランチまたはタグが GitLab で**保護されている**必要があります |

- ワークフローは実行自体のファイルです (GitHub のトップレベルの `workflow_ref`)。再利用可能なアクションやワークフローが公開を実行する場合は、それを呼び出す**あなたの**ワークフロー (例: `.github/workflows/release.yml`) を指定します。
- ref がブランチまたはタグ (`refs/heads/…`、`refs/tags/…`) である実行のみが公開できます。プルリクエストの ref (`refs/pull/…`) は決して公開できません。レジストリは `pull_request_target` の実行を拒否します (フォークのプルリクエストのためにベースブランチの ref で実行されるため)。`workflow_run` は許可されています。それが開始するワークフローでプルリクエストのコードを公開しないでください。
- 追加すると、レジストリはリポジトリを検索し、その数値のリポジトリ ID とオーナー ID を固定します。同じ名前で削除・再作成されたリポジトリは新しい ID を持つため公開できません。意図的にリポジトリを再作成した場合は、トラステッドパブリッシャーを再度追加してください。
- 1 つのパッケージには最大 10 個のトラステッドパブリッシャーを設定できます。

**注意**

ワークフローは内容ではなくパスで照合されます。つまり、ブランチにプッシュできる人なら誰でもそのファイルを編集できます。GitHub では、すべてのトラステッドパブリッシャーに必須レビュアー付きの環境またはデプロイブランチルールを設定してください。ref だけでは、そのブランチが保護されている場合、またはタグがタグルールセットでカバーされている場合にのみ保護されます (そうでなければ、書き込み権限を持つ誰でも編集したワークフローで `v9.9.9` のようなタグをプッシュできます)。GitLab では、レジストリ自体が固定された環境と保護された固定 ref を要求します。

## 使用する CLI

トラステッドパブリッシングには 0.32.0 より新しい `gamedev` CLI が必要です。0.32.0 以前では使用できません。CI では `latest` ではなく正確なバージョンを固定してください。そうしないと、リリースビルドが知らないうちに変わってしまいます。次の安定版リリースまでは、トラステッドパブリッシング対応の CLI は `beta` チャネルにあるため、ここでの例は `@baizor/gamedev@beta` を使用します。そのリリースで `latest` に切り替わります。`gamedev pkg publish` は次の順序で資格情報を選択します:

1. パブリッシャートークン (`--token` または `AI_GAME_DEV_PUBLISHER_TOKEN`) が指定されている場合はそれ。
2. GitHub Actions または GitLab CI で実行されている場合は、その CI の OIDC トークン。
3. サインイン済みのセッション。

GitHub Actions 内、または `AIGD_ID_TOKEN` を使う GitLab ジョブでは、OIDC の設定が欠けていると、追加すべき行を示すエラーになります。そこではセッションは試行されません。`--json` を付けると、結果の `auth` フィールドに使用された資格情報が示されます。Trusted Publishing の場合は `oidc-github` または `oidc-gitlab` です。トークンの audience はレジストリのものと完全に一致している必要があります。本番環境では `ai-game.dev` で、別のレジストリの場合は CLI がそのホスト名を導出します。`--oidc-audience <aud>`（または `AIGD_OIDC_AUDIENCE`）でこれを上書きできます。GitLab では audience はジョブが宣言する `aud` であり、CLI はそれを確認するだけです。

## GitHub Actions から公開する

ジョブには `permissions: id-token: write` が必要です。これがあることで、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
```

信頼済みパブリッシャーで指定したワークフローファイルとして保存します。パブリッシャーパネルには、パッケージの値が入力された同じスニペットが表示されます。

**ヒント**

トークンを要求できる可能性のあるジョブのすべてのステップが、そのトークンを使用できます。依存関係のインストールスクリプトも含まれます。ビルドが許す場合は `npm ci --ignore-scripts` でインストールするか、`id-token: write` を付けない別のジョブでビルドし、`dist/` をアーティファクトとして渡してください。

**公開アクション。** 同じステップをまとめた既製のアクション [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
```

| 入力 | 既定値 | 動作内容 |
| --- | --- | --- |
| `path` | `.` | パッケージフォルダ（`aigd-package.json` を含む） |
| `notes` | 空 | このバージョンのリリースノートを記載した Markdown ファイル |
| `wait` | `true` | レジストリのチェックを待ち、却下された場合はステップを失敗させます（待機終了時にチェックがまだ実行中の場合は失敗しません）。`false` にするとアップロード後に戻ります。 |
| `cli-version` | `latest` | `@baizor/gamedev` のバージョン。正確なバージョン（推奨）または dist-tag。 |
| `audience` | 空 | OIDC の audience。本番以外のレジストリの場合のみ。 |
| `node-version` | `22` | CLI を実行する Node.js |

出力 `result` は CLI の JSON 出力です。アップロード時は id、version、state、integrity、auth、および（待機した場合は）チェックレポートを含みます。アップロード前に実行が失敗した場合は空です。

CI のすべての行を自分のリポジトリに保つには、アクションの `action.yml` を `.github/actions/publish-package/` にコピーし、代わりに `uses: ./.github/actions/publish-package` を使います。GitHub から参照する場合は、アクションをコミット SHA に固定してください。

## GitLab CI から公開する

ジョブは audience `ai-game.dev` の ID トークン `AIGD_ID_TOKEN` を宣言します。1 つのプレーンな文字列で、リストではありません。GitLab はそれをジョブの環境に置き、CLI がそこから読み取ります。 GitLab はジョブの開始時にトークンを発行し、レジストリは発行から 1 時間以内の ID トークンのみを受け付けます。開始から 1 時間以上経って公開するジョブは `OIDC_TOKEN_TOO_OLD` で失敗するため、公開は短い専用のジョブで行ってください。

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

このジョブは、信頼済みパブリッシャーで指定した CI 設定ファイル（既定では `.gitlab-ci.yml`）に置きます。GitLab で `registry` 環境とリリースタグを保護してください。レジストリは保護されていない固定環境や ref を拒否します。GitLab.com に対応しています。

**テンプレート。** 同じリポジトリに、隠しジョブ `.aigd-publish-package` を含む GitLab CI テンプレートがあります。それを include してジョブを extend します。

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

テンプレートをプロジェクトにコピーし（たとえば `ci/publish-package.gitlab-ci.yml` として）、代わりに `local:` で include することもできます。

## 実行が拒否されたとき

`publish` はレジストリの理由と、信頼済みパブリッシャーが一致すべき内容を表示し、何もアップロードせずに終了コード 1 で終了します。`id-token: write` や `id_tokens` エントリがなく、パブリッシャートークンもないジョブには、追加すべき行が示されます。アップロード用の資格情報は 15 分間有効です。チェックにそれ以上かかる場合、ステップはその判定なしで終了します。判定はパブリッシャーパネルで、または新しい CI 実行やサインイン済みのコンピューターから `gamedev pkg publish` で確認してください（同じバージョンを二度アップロードすることはなく、同じ CI トークンは二度使えません）。

## レジストリがチェックする内容

- **トークン:** `https://token.actions.githubusercontent.com` または `https://gitlab.com` によって発行され、プロバイダーの現在の鍵で署名され、audience が正確に `ai-game.dev` で、有効期間内（多少のクロックスキューは許容）であり、過去に見られたことがないこと。また、交換の 1 時間以内に発行されたものである必要があります。
- **一致:** 固定されたリポジトリとオーナーの id、ワークフローファイル（GitHub はトップレベルの workflow ref、GitLab は CI config ref）、ブランチまたはタグでの実行、および信頼済みパブリッシャーが設定している場合は環境と ref。
- **アップロード:** 資格情報は 1 つのパッケージに対してのみ有効で、15 分後に期限切れになります。バージョンは他のアップロードと同様に、すべての[自動チェック](https://ai-game.dev/ja/docs/wiki/app/package-registry#checks)に合格する必要があります。

一致しない場合は拒否され、CLI がその旨を表示します（[上記](https://ai-game.dev/ja/docs/wiki/app/trusted-publishing#refused)参照）。リポジトリ、ワークフローファイル、および実行で使用された環境または ref を確認してください。

## 来歴

Trusted Publishing を通じて公開されたバージョンには、その出所が記録されます:

| フィールド | 例 |
| --- | --- |
| `provider` | `github` |
| `repository`、`repositoryId` | `acme/level-tools`、その数値 id |
| `commit`、`ref` | 実行のコミットSHAとgit ref |
| `workflow` | `.github/workflows/publish.yml` |
| `runId`、`runUrl` | CIの実行とそのリンク |
| `environment` | ジョブがenvironmentを使用した場合 |

来歴は検証済みトークンから取得され、パッケージから取得されることはなく、不変です。署名済みのコミュニティインデックスには各バージョンのプロバイダー、リポジトリ、コミット、ワークフロー、実行へのリンクが含まれており、アプリはそうしたバージョンがどこでビルドされたか（たとえば「built on GitHub Actions」と、リポジトリ、コミット、ワークフロー、実行へのリンク）を表示するため、ユーザーはパッケージをたどって、それをビルドした正確なコミットとCI実行まで確認できます。

## 代わりにパブリッシャートークンを使う

Trusted Publishingが利用できない場合（別のCI、セルフホストのGitLab、自分のコンピューター上のスクリプトなど）は、パブリッシャートークンを使用します。

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

トークン（`agd_pub_…`）は1つのパブリッシャーに属し、一度だけ表示され、最長365日で失効し、アップロード、バージョンのステータス読み取り、yankのみが可能です。パブリッシャーは最大10個の有効なトークンを持てます。トークンは`gamedev pkg publisher token revoke acme <token id>`で、またはパブリッシャーパネルで失効させられます。トークンでアップロードされたバージョンには来歴が付きません。

## 関連ページ

- リリースノート、チャネル、非推奨化については[パッケージの公開](https://ai-game.dev/ja/docs/wiki/app/publishing-packages)をご覧ください。
- すべてのバージョンが通過するチェックについては[レジストリのルールとチェック](https://ai-game.dev/ja/docs/wiki/app/package-registry)をご覧ください。

---

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

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