本頁面由英文機器翻譯而成。閱讀英文原文。

信任發布

從 GitHub Actions 或 GitLab CI 發布 AI Game Dev 套件,不必存放權杖:設定信任發布者、工作流程檔案與來源證明。

更新於 2026年11月19日 以 Markdown 檢視

信任發布讓 CI 工作不必在 CI 中存放任何祕密就能發布套件:GitHub Actions 或 GitLab CI 會證明是哪個儲存庫與工作流程正在執行,ai-game.dev 再把這份證明換成一份只能上傳單一套件的短效憑證。每個以這種方式發布的版本都會記錄其來源證明:建置所用的儲存庫、提交與 CI 執行。本頁說明如何在 GitHub 與 GitLab 上設定,以及會檢查哪些項目。

運作方式

  1. 你告訴註冊表哪個儲存庫與工作流程可以發布套件:這就是信任發布者。
  2. 你的 CI 工作執行 gamedev pkg publish,不帶發布者權杖。CLI 會偵測到自己是在 GitHub Actions(ACTIONS_ID_TOKEN_REQUEST_URL)或 GitLab CI(AIGD_ID_TOKEN)中執行,並向 CI 索取受眾為 ai-game.dev 的 OIDC 身分權杖。
  3. CLI 會把該權杖送到 POST /api/registry/v1/oidc/token。註冊表會驗證它(簽發者、簽章、受眾 ai-game.dev、有效期限),並與該套件的信任發布者比對。
  4. 比對成功時,它會回傳一組憑證(agd_oidc_…),有效期 15 分鐘,僅限該單一套件,且只能用於上傳與讀取版本狀態。CLI 便以它上傳。
  5. 註冊表會在新版本上記錄該次執行的來源證明。之後永不會變更。

沒有任何長效憑證可能外洩:CI 祕密中沒有權杖,也沒有東西需要輪替。同一個 OIDC 權杖不能兌換兩次,每次兌換都會記錄在註冊表的稽核日誌中。

新增信任發布者

在發布者面板中開啟該套件,然後前往 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,或結尾帶一個 * 的前綴,例如 refs/tags/v*同上,且該分支或標籤在 GitLab 中必須是受保護的
  • 工作流程指的是該次執行本身的檔案(GitHub 最上層的 workflow_ref)。若由可重複使用的 action 或工作流程負責發布,請填寫你的呼叫它的工作流程,例如 .github/workflows/release.yml。
  • 只有 ref 為分支或標籤(refs/heads/…、refs/tags/…)的執行才能發布;拉取請求的 ref(refs/pull/…)絕不可能發布。登錄庫會拒絕 pull_request_target 執行(它們代表分叉的拉取請求,以基底分支的 ref 執行)。workflow_run 是允許的:不要讓由它啟動的工作流程發布來自拉取請求的程式碼。
  • 新增時,註冊表會查詢該儲存庫並固定其數字形式的儲存庫與擁有者 id。若儲存庫被刪除後以相同名稱重建,就會有新的 id 而無法發布:如果你刻意重建儲存庫,請重新新增信任發布者。
  • 一個套件最多可有 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. CI 的 OIDC 權杖,若在 GitHub Actions 或 GitLab CI 中執行;
  3. 你已登入的工作階段。

在 GitHub Actions 中,或是在帶有 AIGD_ID_TOKEN 的 GitLab job 中,若缺少 OIDC 設定,就會產生一個指出應新增哪一行的錯誤;該處不會嘗試建立 session。使用 --json 時,結果的 auth 欄位會指出所用的憑證:Trusted Publishing 為 oidc-github 或 oidc-gitlab。權杖的 audience 必須與 registry 完全一致:正式環境為 ai-game.dev,若是其他 registry,CLI 會推導出其主機名稱。--oidc-audience <aud>(或 AIGD_OIDC_AUDIENCE)會覆寫該值;在 GitLab 上,audience 就是 job 所宣告的 aud,CLI 只會檢查它。

從 GitHub Actions 發布

該 job 需要 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

將它存成你在 trusted publisher 上指定的 workflow 檔案。發布者面板會顯示相同的片段,並填入你套件的值。

發布 action。 相同的步驟也包裝成可直接使用的 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
輸入預設值功能說明
path.套件資料夾(內含 aigd-package.json)
notes空包含此版本發行說明的 Markdown 檔案
waittrue等待 registry 的檢查,並在遭到拒絕時讓該步驟失敗(等待結束時仍在執行的檢查不會使其失敗);false 則在上傳後即返回
cli-versionlatest@baizor/gamedev 的版本,可為確切版本(建議)或 dist-tag
audience空OIDC audience,僅用於非正式環境的 registry
node-version22執行 CLI 的 Node.js

其輸出 result 就是 CLI 的 JSON 輸出:上傳時包含 id、version、state、integrity、auth,以及(若有等待)檢查報告;若執行在上傳前就失敗則為空。

若想讓 CI 的每一行都留在自己的 repository 中,可將該 action 的 action.yml 複製到 .github/actions/publish-package/,並改用 uses: ./.github/actions/publish-package;若從 GitHub 引用該 action,請將其固定到某個 commit SHA。

從 GitLab CI 發布

該 job 宣告一個名為 AIGD_ID_TOKEN 的 ID token,audience 為 ai-game.dev,是單一字串而非清單。GitLab 會將它放入 job 的環境中,CLI 便從那裡讀取。GitLab 會在 job 開始時簽發它,而登錄庫只接受簽發後一小時內的 ID token:在開始一小時後才發布的 job 會以 OIDC_TOKEN_TOO_OLD 失敗,因此請在一個簡短的獨立 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.0

此 job 位於你在 trusted publisher 上指定的 CI 設定檔中(預設為 .gitlab-ci.yml)。請在 GitLab 中保護 registry environment 與你的 release tag:registry 會拒絕未受保護的 pinned environment 或 ref。支援 GitLab.com。

範本。 同一個 repository 內含一個 GitLab CI 範本,其中有個隱藏 job .aigd-publish-package。將其 include 並 extend 該 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_TAG

你也可以將範本複製到你的專案中(例如命名為 ci/publish-package.gitlab-ci.yml),並改用 local: 來 include。

當執行遭拒時

publish 會印出 registry 的原因以及 trusted publisher 必須符合的條件,不上傳任何內容並以 1 結束。若 job 沒有 id-token: write 或 id_tokens 項目,也沒有 publisher token,則會告知需新增哪一行。上傳憑證有效期為 15 分鐘:若檢查耗時更久,該步驟會在沒有其結論的情況下結束;可在發布者面板中查看,或從新的 CI 執行、或在你已登入的電腦上以 gamedev pkg publish 查看(它絕不會重複上傳同一版本;同一個 CI token 也不能使用兩次)。

registry 會檢查什麼

  • 權杖: 由 https://token.actions.githubusercontent.com 或 https://gitlab.com 簽發,以供應商目前的金鑰簽署,audience 必須正好是 ai-game.dev,且在其有效期內(允許些微的時鐘偏差),並且從未出現過。它還必須是在交換前一小時內簽發的。
  • 相符條件: 固定的 repository 與 owner id、workflow 檔案(GitHub 的最上層 workflow ref、GitLab 的 CI 設定 ref)、分支或 tag 執行,以及 trusted publisher 有設定時的 environment 與 ref。
  • 上傳: 該憑證僅對其單一套件有效,並在 15 分鐘後過期。該版本仍會像其他上傳一樣通過所有自動檢查。

不符就會被拒絕,CLI 會如此告知(見上方)。請檢查 repository、workflow 檔案,以及該次執行所用的 environment 或 ref。

來源出處

透過 Trusted Publishing 發布的版本會記錄其來源:

欄位範例
providergithub
repository、repositoryIdacme/level-tools,其數字 id
commit、ref該次執行的 commit SHA 與 git ref
workflow.github/workflows/publish.yml
runId、runUrl該次 CI 執行及其連結
environment當工作有使用環境時

來源證明取自經驗證的權杖,絕非來自套件本身,且不可變更。經簽署的社群索引會記錄每個版本的提供者、儲存庫、commit、workflow 與執行連結,應用程式也會顯示這類版本的建置來源(例如「built on GitHub Actions」,並附上儲存庫、commit、workflow 與該次執行的連結),讓使用者能從套件一路追溯回建置它的確切 commit 與 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_…)隸屬於單一發佈者,僅顯示一次,最多 365 天後到期,且只能上傳、讀取版本狀態與 yank。每位發佈者最多可有 10 個有效權杖;可用 gamedev pkg publisher token revoke acme <token id> 或在發佈者面板中撤銷權杖。使用權杖上傳的版本不帶來源證明。