自动化插件发布

自动化发布在你推送版本标签或手动启动 GitHub Actions 工作流时构建并发布沙箱插件。你的 Atmosphere 账户拥有包配置文件和发布记录。GitHub 识别已批准的工作流，发布服务在不将账户凭据存储在仓库中的情况下验证并发布结果。

对于从你的计算机发起的发布，使用 emdash-plugin publish。当 GitHub Actions 需要构建和发布版本时，使用本指南。

前置条件

开始之前准备以下内容：

一个包含沙箱 EmDash 插件的公开 GitHub 仓库。
一个有效的 emdash-plugin.jsonc，包含 slug、publisher、license、作者和安全联系人。将 repo 设置为规范的 GitHub URL，或在交互式设置期间输入。
package.json 中的版本，或对于仅注册表插件在 emdash-plugin.jsonc 中的版本。
publisher 指定的 Atmosphere 账户。
向仓库添加 GitHub Actions 密钥的权限。
支持通行密钥的浏览器。发布审批需要用户验证。

在配置工作流之前运行清单检查：

pnpm exec emdash-plugin validate

设置自动化发布

使用拥有该包的 Atmosphere 账户登录插件 CLI。
```
pnpm exec emdash-plugin login alice.example.com
```
CLI 将此本地发布会话存储在项目之外。GitHub Actions 永远不会接收到它。
准备包配置文件并生成工作流。
```
pnpm exec emdash-plugin release setup
```
该命令从 emdash-plugin.jsonc 读取包元数据。如果包配置文件缺失，它会提议创建。如果配置文件存在但没有委托发布设置，它会提议在保留现有包元数据的同时添加这些设置。

设置会询问何时需要审批发布：
- 当插件权限增加时 是默认选项。当声明的访问权限相对于最新发布扩展时，发布等待审批。
- 每次发布 要求每个版本都需要审批。
已登录的 Atmosphere 账户成为初始审批者。配置文件还将包绑定到规范的 GitHub 仓库 URL，并要求可验证的来源。

当工作流文件已存在时，仅运行配置文件步骤：
```
pnpm exec emdash-plugin profile setup
```
在非交互式终端中，传递 --yes 接受默认审批策略。当清单不包含 repo 时传递 --repository <https-url>，传递 --confirmation always 以要求每次发布都需审批。
审查并提交生成的工作流。

该命令创建 .github/workflows/emdash-release.yml。它不会推送文件，除非你传递 --force，否则不会替换现有工作流。

生成的工作流在匹配 v* 的版本标签和 workflow_dispatch 时运行。它授予 contents: read、id-token: write 和 attestations: write；将第三方 Actions 固定到完整的提交标识符；构建一个插件 bundle；为这些确切字节创建 GitHub 构建来源；并将两个文件传递给 EmDash 发布 Action。
打开发布服务仪表板并使用相同的 Atmosphere 账户登录。

选择 Authorize publishing。你的账户提供者显示确切的委托权限。保留的授权可以创建包发布记录并上传包或列表图片 Blob。它不能创建或编辑包配置文件、更新或删除发布、或写入其他集合。
创建工作流邀请。

输入 emdash-plugin.jsonc 中的插件 ID，然后选择 Create invitation。将一次性值作为名为 EMDASH_CONNECTION_INVITATION 的 Actions 密钥添加到 GitHub 仓库。

邀请有效期为 30 分钟，只能连接指定的插件。如果在工作流消费之前过期，请创建新的邀请。
启动发布工作流。

在创建版本标签之前更新包版本。以下命令启动 1.2.3 发布：
```
git tag v1.2.3
git push origin v1.2.3
```
你也可以在仓库的 GitHub Actions 页面选择 Run workflow。
在首次运行时批准工作流连接。

Action 在 GitHub 作业摘要中写入链接并等待。打开链接并确认插件、仓库、工作流文件、分支或标签和环境。

对于标签触发的运行，选择 All version tags 或 Only this tag。分支触发的请求仅覆盖该分支。服务存储 GitHub 仓库和所有者 ID 以及所选的 ref 和环境范围。后续运行必须匹配此策略。
需要时审批发布。

扩展插件权限的发布，或配置为每次发布确认的配置文件，进入 Awaiting approval 状态。从 Action 输出或发布仪表板打开审批 URL。如果审批账户还没有通行密钥，请注册一个，审查权限变更，然后批准或拒绝发布。

Action 的默认设置在发布达到 Awaiting approval 时成功返回。服务工作流继续等待浏览器决定，在批准后发布。

发布服务验证的内容

服务在写入发布之前完成以下检查：

GitHub OpenID Connect（OIDC）令牌指定了经授权的仓库、所有者、工作流、ref、环境、提交、运行和 GitHub 托管运行器。
包配置文件存在，由发布者签名，包含委托发布设置，并指定相同的规范 GitHub 仓库。
请求的包和版本与构建的插件 bundle 匹配。
包校验和与上传的字节匹配。
GitHub 来源覆盖相同的 bundle、仓库、工作流、提交和运行。
发布记录的声明访问权限与 bundle 清单匹配。
版本记录尚不存在。
任何必需的通行密钥审批覆盖确切的验证结果和当前配置文件修订。

Action 为每次服务调用请求一个新的 GitHub OIDC 令牌。Bundle 和来源文件仅在工作流被授权后进入私有临时存储。服务将经验证的包和图片字节上传到发布者的个人数据服务器（PDS），在那里创建发布记录，并通过不可变的校验和寻址 URL 公开经验证的来源。

权限边界

每个凭据都有一个职责：

凭据	使用者	权限
本地 CLI OAuth 会话	`emdash-plugin profile setup`	在本地确认后创建或更新发布者拥有的包配置文件。
GitHub OIDC 令牌	发布 Action	向服务标识一次 GitHub 工作流运行。不授予 AT Protocol 写入访问权限。
发布服务委托	发布服务	创建包发布记录并上传所需的 Blob。
发布者应用程序会话	发布仪表板	授权工作流连接和撤销委托发布。
审批者会话和通行密钥	审批页面	批准或拒绝一次校验和绑定的发布验证。
Cloudflare Access 身份	服务运维控制台	运维托管服务。不代表发布者或审批者。

服务分别存储发布者和审批者状态。登录查看你的发布不会授予运维访问权限，运维身份不能作为发布者批准发布。

Action 行为

生成的工作流使用 apps/release-action 中的 Action。Action 接受构建的 bundle 加上原始 Sigstore 来源，或包含校验和绑定的 HTTPS 工件源的兼容性 release-file。不要将 release-file 与 bundle 或来源输入组合使用。

标准生成的工作流提供以下输入：

输入	值
`service-url`	发布服务 HTTPS 来源。
`publisher-did`	拥有包配置文件和发布的 DID。
`connection-invitation`	首次连接时的 `EMDASH_CONNECTION_INVITATION`。
`bundle-file`	`emdash-plugin bundle` 生成的单个 tarball。
`provenance-file`	`actions/attest-build-provenance` 的原始 `bundle-path` 输出。

Action 返回以下输出：

输出	含义
`connection-url`	首次运行时工作流审批的浏览器 URL。
`intent-id`	发布意图标识符。
`state`	Published、终端或 `awaiting_approval` 状态。
`approval-url`	需要通行密钥审批时的浏览器 URL。
`release-uri`	已发布发布的 AT URI。
`release-cid`	已发布发布记录的 CID。
`reason-code`	终端意图的稳定原因。

有关可选输入、自定义 URL 源工作流、轮询控制和确切输出行为，请参阅 Action 参考。

故障排除

`PACKAGE_PROFILE_REQUIRED`

包配置文件缺失、缺少委托发布设置、使用非规范的仓库 URL，或指定了与 GitHub 工作流不同的仓库。

使用发布者账户在本地运行配置文件设置，然后重新启动工作流：

pnpm exec emdash-plugin profile setup

此检查在服务接受 bundle 或来源上传之前运行。

需要公开仓库

GitHub 对私有和内部仓库使用私有 Sigstore 信任根。发布验证者目前仅信任公共 GitHub 来源。将发布工作流移到公开仓库，或使用 emdash-plugin publish 在本地发布。

邀请已过期或无效

在发布仪表板中创建另一个邀请并替换 EMDASH_CONNECTION_INVITATION。在 30 分钟内启动工作流。邀请是一次性的，限定为一个插件 ID。

`WORKLOAD_NOT_ALLOWED`

GitHub 仓库、所有者、工作流文件、ref 或环境与已批准的工作流策略不匹配。打开发布仪表板并使用预期的范围批准新的工作流连接。

`PROFILE_FETCH_FAILED`

服务无法从发布者的 PDS 验证配置文件。在账户提供者可用后重试。如果配置文件已被删除或更改，运行 emdash-plugin profile setup。

`POLL_TIMEOUT`

Action 在工作流审批、发布审批或发布完成之前达到了 timeout-minutes。在重新运行之前检查发布仪表板中的意图状态。相同 GitHub Actions 运行的重新运行会重用其幂等键。

撤销自动化发布

在发布仪表板中选择 Turn off automated publishing。撤销会清除保留的发布委托。现有的包配置文件、发布、审核标签、已安装的插件和仪表板登录不会改变。

在下次自动化发布之前，重新连接发布并再次批准工作流。