このページは英語から機械翻訳されています。英語の原文を読む。

トラステッドパブリッシング

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

2026年11月19日に更新 Markdownで表示

トラステッドパブリッシングを使うと、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 回交換することはできず、すべての交換はレジストリの監査ログに記録されます。

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

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

フィールドGitHub Actions の場合GitLab CI の場合
プロバイダーgithubgitlab
リポジトリ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 は次の順序で資格情報を選択します:

  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 のトークンを要求できます。

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 ファイル
waittrueレジストリのチェックを待ち、却下された場合はステップを失敗させます(待機終了時にチェックがまだ実行中の場合は失敗しません)。false にするとアップロード後に戻ります。
cli-versionlatest@baizor/gamedev のバージョン。正確なバージョン(推奨)または dist-tag。
audience空OIDC の audience。本番以外のレジストリの場合のみ。
node-version22CLI を実行する 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 を通じて公開されたバージョンには、その出所が記録されます:

フィールド例
providergithub
repository、repositoryIdacme/level-tools、その数値 id
commit、ref実行のコミットSHAとgit ref
workflow.github/workflows/publish.yml
runId、runUrlCIの実行とそのリンク
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>で、またはパブリッシャーパネルで失効させられます。トークンでアップロードされたバージョンには来歴が付きません。