トラステッドパブリッシング
GitHub Actions や GitLab CI からトークンを保存せずに AI Game Dev パッケージを公開する方法: トラステッドパブリッシャー、ワークフローファイル、provenance の設定。
トラステッドパブリッシングを使うと、CI にシークレットを保存することなく CI ジョブからパッケージを公開できます。GitHub Actions または GitLab CI が、どのリポジトリとワークフローが実行されているかを保証し、ai-game.dev はその証明を、1 つのパッケージをアップロードできる短期間有効な資格情報と引き換えます。この方法で公開されたすべてのバージョンには provenance が記録されます。provenance には、どのリポジトリ、コミット、CI 実行からビルドされたかが含まれます。このページでは、GitHub と GitLab での設定方法と、何が検証されるかを説明します。
仕組み
- どのリポジトリとワークフローがパッケージを公開できるかをレジストリに登録します。これがトラステッドパブリッシャーです。
- CI ジョブはパブリッシャートークンなしで
gamedev pkg publishを実行します。CLI は自分が GitHub Actions (ACTIONS_ID_TOKEN_REQUEST_URL) または GitLab CI (AIGD_ID_TOKEN) で実行されていることを検知し、オーディエンスai-game.devで OIDC ID トークンを CI に要求します。 - CLI はそのトークンを
POST /api/registry/v1/oidc/tokenに送信します。レジストリはトークンを検証し (発行者、署名、オーディエンスai-game.dev、有効期限)、パッケージのトラステッドパブリッシャーと照合します。 - 一致すると、15 分間有効で、その 1 つのパッケージ専用の資格情報 (
agd_oidc_…) を返します。これはバージョンのアップロードとステータスの読み取りにのみ使用できます。CLI はこの資格情報でアップロードします。 - レジストリは新しいバージョンにその実行の provenance を記録します。これは後から変更されることはありません。
漏えいする可能性のある長期間有効なものはありません。CI シークレットにトークンはなく、ローテーションする必要もありません。同じ OIDC トークンを 2 回交換することはできず、すべての交換はレジストリの監査ログに記録されます。
トラステッドパブリッシャーを追加する
パブリッシャーパネル でパッケージを開き、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 個のトラステッドパブリッシャーを設定できます。
使用する CLI
トラステッドパブリッシングには 0.32.0 より新しい gamedev CLI が必要です。0.32.0 以前では使用できません。CI では latest ではなく正確なバージョンを固定してください。そうしないと、リリースビルドが知らないうちに変わってしまいます。次の安定版リリースまでは、トラステッドパブリッシング対応の CLI は beta チャネルにあるため、ここでの例は @baizor/gamedev@beta を使用します。そのリリースで latest に切り替わります。gamedev pkg publish は次の順序で資格情報を選択します:
- パブリッシャートークン (
--tokenまたはAI_GAME_DEV_PUBLISHER_TOKEN) が指定されている場合はそれ。 - GitHub Actions または GitLab CI で実行されている場合は、その CI の OIDC トークン。
- サインイン済みのセッション。
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 のトークンを要求できます。
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信頼済みパブリッシャーで指定したワークフローファイルとして保存します。パブリッシャーパネルには、パッケージの値が入力された同じスニペットが表示されます。
公開アクション。 同じステップをまとめた既製のアクション 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| 入力 | 既定値 | 動作内容 |
|---|---|---|
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 で失敗するため、公開は短い専用のジョブで行ってください。
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 します。
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 分後に期限切れになります。バージョンは他のアップロードと同様に、すべての自動チェックに合格する必要があります。
一致しない場合は拒否され、CLI がその旨を表示します(上記参照)。リポジトリ、ワークフローファイル、および実行で使用された環境または 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、自分のコンピューター上のスクリプトなど)は、パブリッシャートークンを使用します。
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>で、またはパブリッシャーパネルで失効させられます。トークンでアップロードされたバージョンには来歴が付きません。
関連ページ
- リリースノート、チャネル、非推奨化についてはパッケージの公開をご覧ください。
- すべてのバージョンが通過するチェックについてはレジストリのルールとチェックをご覧ください。