可信发布
在 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、有效期),并将其与该包的可信发布者进行匹配。 - 匹配成功后返回一个有效期为 15 分钟 的凭证(
agd_oidc_…),仅限该单个包使用,且只能用于上传和读取某个版本的状态。CLI 用它来上传。 - 注册中心会在新版本上记录本次运行的来源信息。此后它永远不再改变。
不存在任何长期有效的秘密可供泄露:CI 密钥里没有令牌,也没有需要轮换的东西。同一个 OIDC 令牌不能被交换两次,每次交换都会记录在注册中心的审计日志中。
添加可信发布者
在发布者面板中打开该包,进入 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 个可信发布者。
使用哪个 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 作业里,缺少 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 的令牌。
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将其保存为你在受信任发布者上指定的工作流文件。发布者面板会显示相同的代码片段,并填入你软件包的取值。
发布 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 | 等待注册表的检查,并在被拒绝时使该步骤失败(等待结束时仍在运行的检查不会导致失败);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 失败,因此请在一个简短的独立作业中发布。
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 进来并扩展该作业:
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 分钟后过期。该版本仍会像其他任何上传一样通过所有自动检查。
不匹配即会被拒绝,CLI 会说明原因(见上文)。请检查仓库、工作流文件,以及该次运行使用的环境或 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 天后过期,且只能上传、读取某个版本的状态和撤下版本。一个发布者最多有 10 个有效令牌;可用 gamedev pkg publisher token revoke acme <token id> 或在发布者面板中撤销令牌。使用令牌上传的版本不携带来源信息。