信任發布
從 GitHub Actions 或 GitLab CI 發布 AI Game Dev 套件,不必存放權杖:設定信任發布者、工作流程檔案與來源證明。
信任發布讓 CI 工作不必在 CI 中存放任何祕密就能發布套件:GitHub Actions 或 GitLab CI 會證明是哪個儲存庫與工作流程正在執行,ai-game.dev 再把這份證明換成一份只能上傳單一套件的短效憑證。每個以這種方式發布的版本都會記錄其來源證明:建置所用的儲存庫、提交與 CI 執行。本頁說明如何在 GitHub 與 GitLab 上設定,以及會檢查哪些項目。
運作方式
- 你告訴註冊表哪個儲存庫與工作流程可以發布套件:這就是信任發布者。
- 你的 CI 工作執行
gamedev pkg publish,不帶發布者權杖。CLI 會偵測到自己是在 GitHub Actions(ACTIONS_ID_TOKEN_REQUEST_URL)或 GitLab CI(AIGD_ID_TOKEN)中執行,並向 CI 索取受眾為ai-game.dev的 OIDC 身分權杖。 - CLI 會把該權杖送到
POST /api/registry/v1/oidc/token。註冊表會驗證它(簽發者、簽章、受眾ai-game.dev、有效期限),並與該套件的信任發布者比對。 - 比對成功時,它會回傳一組憑證(
agd_oidc_…),有效期 15 分鐘,僅限該單一套件,且只能用於上傳與讀取版本狀態。CLI 便以它上傳。 - 註冊表會在新版本上記錄該次執行的來源證明。之後永不會變更。
沒有任何長效憑證可能外洩:CI 祕密中沒有權杖,也沒有東西需要輪替。同一個 OIDC 權杖不能兌換兩次,每次兌換都會記錄在註冊表的稽核日誌中。
新增信任發布者
在發布者面板中開啟該套件,然後前往 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,或結尾帶一個 * 的前綴,例如 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 依下列順序選擇憑證:
- 發布者權杖(
--token或AI_GAME_DEV_PUBLISHER_TOKEN),若有提供; - CI 的 OIDC 權杖,若在 GitHub Actions 或 GitLab CI 中執行;
- 你已登入的工作階段。
在 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 檔案 |
wait | true | 等待 registry 的檢查,並在遭到拒絕時讓該步驟失敗(等待結束時仍在執行的檢查不會使其失敗);false 則在上傳後即返回 |
cli-version | latest | @baizor/gamedev 的版本,可為確切版本(建議)或 dist-tag |
audience | 空 | OIDC audience,僅用於非正式環境的 registry |
node-version | 22 | 執行 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 發布的版本會記錄其來源:
| 欄位 | 範例 |
|---|---|
provider | github |
repository、repositoryId | acme/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> 或在發佈者面板中撤銷權杖。使用權杖上傳的版本不帶來源證明。