# 信任發布 — AI Game Dev 應用程式與 CLI · AI Game Developer Wiki

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

本頁面由英文機器翻譯而成。[閱讀英文原文](https://ai-game.dev/docs/wiki/app/trusted-publishing)。

信任發布讓 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 權杖不能兌換兩次，每次兌換都會記錄在註冊表的稽核日誌中。

## 新增信任發布者

在[發布者面板](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`，或結尾帶一個 `*` 的前綴，例如 `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 個信任發布者。

**警告**

工作流程是依路徑比對，而非內容：任何能推送分支的人都能編輯該檔案。在 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. 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` 的權杖的原因。

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

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

**提示**

一個可能請求該權杖的 job，其每個步驟都能使用它，包括你的相依套件的安裝腳本。若你的建置允許，請以 `npm ci --ignore-scripts` 安裝，或在另一個沒有 `id-token: write` 的 job 中建置，並將 `dist/` 以 artifact 傳遞。

**發布 action。** 相同的步驟也包裝成可直接使用的 action，[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` | 等待 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 中發布。

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

此 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：

```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` 會印出 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 分鐘後過期。該版本仍會像其他上傳一樣通過所有[自動檢查](https://ai-game.dev/zh-hant/docs/wiki/app/package-registry#checks)。

不符就會被拒絕，CLI 會如此告知（見[上方](https://ai-game.dev/zh-hant/docs/wiki/app/trusted-publishing#refused)）。請檢查 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、你電腦上的腳本），請改用發佈者權杖：

```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_…`）隸屬於單一發佈者，僅顯示一次，最多 365 天後到期，且只能上傳、讀取版本狀態與 yank。每位發佈者最多可有 10 個有效權杖；可用 `gamedev pkg publisher token revoke acme <token id>` 或在發佈者面板中撤銷權杖。使用權杖上傳的版本不帶來源證明。

## 相關頁面

- [發佈套件](https://ai-game.dev/zh-hant/docs/wiki/app/publishing-packages)：說明發行說明、頻道與棄用。
- [登錄規則與檢查](https://ai-game.dev/zh-hant/docs/wiki/app/package-registry)：每個版本都會通過的檢查。

---

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

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