# 可信发布 — 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. 匹配成功后返回一个有效期为 **15 分钟** 的凭证（`agd_oidc_…`），仅限**该单个包**使用，且只能用于上传和读取某个版本的状态。CLI 用它来上传。
5. 注册中心会在新版本上记录本次运行的来源信息。此后它永远不再改变。

不存在任何长期有效的秘密可供泄露：CI 密钥里没有令牌，也没有需要轮换的东西。同一个 OIDC 令牌不能被交换两次，每次交换都会记录在注册中心的审计日志中。

## 添加可信发布者

在[发布者面板](https://ai-game.dev/publisher)中打开该包，进入 **Trusted publishing**，然后添加一个。你必须是该包所属发布者的 **owner**。包不必已经存在：为新包 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。同名删除后重建的仓库会有新的 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 作业里，缺少 OIDC 配置会报错并指出需要添加的那一行；在这类环境中不会尝试使用该会话。使用 `--json` 时，结果的 `auth` 字段会指明所用的凭据：Trusted Publishing 为 `oidc-github` 或 `oidc-gitlab`。令牌的受众必须与注册表完全一致：生产环境为 `ai-game.dev`，对于其他注册表，CLI 会根据其主机名推导。`--oidc-audience <aud>`（或 `AIGD_OIDC_AUDIENCE`）可覆盖该值；在 GitLab 上，受众是作业声明的 `aud`，CLI 只对其进行校验。

## 从 GitHub Actions 发布

该作业需要 `permissions: id-token: write`；正是它让作业能够请求受众为 `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
```

将其保存为你在受信任发布者上指定的工作流文件。发布者面板会显示相同的代码片段，并填入你软件包的取值。

**提示**

可能请求令牌的作业的每一步都能使用它，包括依赖项的安装脚本。在构建允许的情况下使用 `npm ci --ignore-scripts` 安装，或者在不含 `id-token: write` 的独立作业中构建，并通过构件传递 `dist/`。

**发布 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` | 等待注册表的检查，并在被拒绝时使该步骤失败（等待结束时仍在运行的检查不会导致失败）；`false` 则在上传后立即返回 |
| `cli-version` | `latest` | `@baizor/gamedev` 的版本，可以是精确版本（推荐）或 dist-tag |
| `audience` | 空 | OIDC 受众，仅用于非生产环境的注册表 |
| `node-version` | `22` | 运行 CLI 的 Node.js 版本 |

其输出 `result` 即 CLI 的 JSON 输出：上传时包含 id、版本、状态、完整性、auth 以及（若进行了等待）检查报告；若运行在上传前失败则为空。

若想让 CI 的每一行都留在自己的仓库中，可将该 action 的 `action.yml` 复制到 `.github/actions/publish-package/`，改用 `uses: ./.github/actions/publish-package`；如果你从 GitHub 引用该 action，请将其固定到某个提交 SHA。

## 从 GitLab CI 发布

该作业声明一个名为 `AIGD_ID_TOKEN` 的 ID 令牌，受众为 `ai-game.dev`，为单个普通字符串，而非列表。GitLab 会将其放入作业的环境变量中，CLI 从那里读取。GitLab 在作业开始时签发该令牌，而注册表只接受签发后一小时内的 ID 令牌：在开始一小时后才发布的作业会以 `OIDC_TOKEN_TOO_OLD` 失败，因此请在一个简短的独立作业中发布。

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

此作业位于你在受信任发布者上指定的 CI 配置文件（默认为 `.gitlab-ci.yml`）中。请在 GitLab 中保护 `registry` 环境和你的发布标签：注册表会拒绝未受保护的固定环境或 ref。支持 GitLab.com。

**模板。** 同一仓库中还包含一个 GitLab CI 模板，其中有一个隐藏作业 `.aigd-publish-package`。将其 include 进来并扩展该作业：

```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:` 引入。

## 运行被拒绝时

`publish` 会打印注册表给出的原因以及受信任发布者必须匹配的内容，不上传任何内容并以 1 退出。缺少 `id-token: write` 或 `id_tokens` 条目、且没有发布者令牌的作业，会被告知需要添加哪一行。上传凭据有效期为 15 分钟：如果检查耗时更长，该步骤会在没有结论的情况下结束；可在发布者面板中读取结论，或通过一次新的 CI 运行或在你已登录的电脑上运行 `gamedev pkg publish` 来读取（它绝不会重复上传同一版本；同一个 CI 令牌不能使用两次）。

## 注册表检查什么

- **令牌：** 由 `https://token.actions.githubusercontent.com` 或 `https://gitlab.com` 签发，使用提供方当前的密钥签名，受众恰好为 `ai-game.dev`，处于其有效期内（允许少量时钟偏差），且此前从未出现过。它还必须是在交换前一小时内签发的。
- **匹配项：** 固定的仓库和所有者 id、工作流文件（GitHub 为顶层工作流 ref，GitLab 为 CI 配置 ref）、分支或标签运行，以及受信任发布者设置的环境和 ref。
- **上传：** 该凭据仅对其对应的一个软件包有效，并在 15 分钟后过期。该版本仍会像其他任何上传一样通过所有[自动检查](https://ai-game.dev/zh-hans/docs/wiki/app/package-registry#checks)。

不匹配即会被拒绝，CLI 会说明原因（见[上文](https://ai-game.dev/zh-hans/docs/wiki/app/trusted-publishing#refused)）。请检查仓库、工作流文件，以及该次运行使用的环境或 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 天后过期，且只能上传、读取某个版本的状态和撤下版本。一个发布者最多有 10 个有效令牌；可用 `gamedev pkg publisher token revoke acme <token id>` 或在发布者面板中撤销令牌。使用令牌上传的版本不携带来源信息。

## 相关页面

- [发布软件包](https://ai-game.dev/zh-hans/docs/wiki/app/publishing-packages)：了解发行说明、渠道和弃用。
- [注册表规则与检查](https://ai-game.dev/zh-hans/docs/wiki/app/package-registry)：了解每个版本都要通过的检查。

---

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

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