自动化插件发布

自动化发布会在你推送版本标签或手动启动 GitHub Actions 工作流时，构建并发布沙箱插件。你的 Atmosphere 账户 仍拥有包配置文件与发布记录。GitHub 识别已批准的工作流，发布服务验证构建，并通过狭窄的委托写入发布记录。仓库不会存储 Atmosphere 账户凭证。

从你的计算机启动发布时，使用 emdash-plugin publish。当应由 GitHub Actions 构建并发布时，使用本指南。

前提条件

开始前请准备：

• 包含沙箱 EmDash 插件的公开 GitHub 仓库。
• 作为开发依赖安装的 @emdash-cms/plugin-cli。用 CLI 创建的插件已包含它。
• 有效的 emdash-plugin.jsonc，包含 slug、publisher、license、作者与安全联系人。将 repo 设为规范 GitHub URL，或在交互式设置中确认检测到的 GitHub 远程。
• package.json 中的版本，或仅注册表插件的 emdash-plugin.jsonc 中的版本。
• publisher 所指定的 Atmosphere 账户。
• 支持通行密钥的浏览器。发布批准需要用户验证。

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

pnpm exec emdash-plugin validate

设置自动化发布

连接 Changesets 工作流

生成的 .github/workflows/emdash-release.yml 通过 workflow_call 接受 Changesets Action 的已发布包 JSON。向现有 Changesets 作业添加输出，然后从依赖作业调用 EmDash 工作流。当现有作业或步骤使用其他 ID 时，替换 release 与 changesets。

Changesets Action v2 使用 published-packages 输出。将以下作业输出与调用方添加到使用 Changesets CLI v3 的工作流：

jobs:
  release:
    # Keep the existing runner, permissions, and steps.
    outputs:
      published: ${{ steps.changesets.outputs.published }}
      published-packages: ${{ steps.changesets.outputs['published-packages'] }}

  publish-emdash-plugins:
    needs: release
    if: needs.release.outputs.published == 'true'
    uses: ./.github/workflows/emdash-release.yml
    with:
      published-packages: ${{ needs.release.outputs['published-packages'] }}
    permissions:
      contents: read
      id-token: write
      attestations: write

Changesets Action v1 使用 camel-case 的 publishedPackages 步骤输出。对使用 Changesets CLI v2 的工作流使用此表达式：

jobs:
  release:
    # Keep the existing runner, permissions, and steps.
    outputs:
      published: ${{ steps.changesets.outputs.published }}
      published-packages: ${{ steps.changesets.outputs.publishedPackages }}

  publish-emdash-plugins:
    needs: release
    if: needs.release.outputs.published == 'true'
    uses: ./.github/workflows/emdash-release.yml
    with:
      published-packages: ${{ needs.release.outputs['published-packages'] }}
    permissions:
      contents: read
      id-token: write
      attestations: write

让 Changesets 负责其版本拉取请求与包发布。仅当 Changesets 报告 published: true 时，EmDash 调用方才运行。对于仅 EmDash 的私有包，在 .changeset/config.json 中将 privatePackages.version 与 privatePackages.tag 都设为 true。将无关的私有应用与测试夹具加入 ignore。

添加另一个包

从其源目录准备包配置文件。现有根工作流与仓库连接会被复用：

pnpm exec emdash-plugin profile setup --dir packages/comments

使用 Changesets 时，将该包加入 changeset 并合并其版本拉取请求。使用包标签触发器时，更新包版本并推送其标签：

git tag comments@1.0.0
git push origin comments@1.0.0

工作流将 comments 解析为一个 emdash-plugin.jsonc，检查所选版本，并在接受制品上传之前验证签名配置文件是否指定了已连接的仓库。重复的包 ID 与版本不匹配会在 attestation 之前失败。

发布服务验证什么

服务在写入发布之前完成这些检查：

1. GitHub OpenID Connect (OIDC) 令牌指定了已授权的仓库、所有者、工作流、ref、环境、提交、运行与 GitHub 托管的运行器。
2. 包配置文件存在，由发布者签名，包含 delegated-release 设置，并指定同一规范 GitHub 仓库。
3. 请求的包与版本与已构建的插件包匹配。
4. 包校验和与上传的字节匹配。
5. GitHub provenance 覆盖同一包、仓库、工作流、提交与运行。
6. 发布记录声明的访问与包清单匹配。
7. 版本记录尚不存在。
8. 任何所需的通行密钥批准覆盖确切的验证结果与当前配置文件修订。

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

权限边界

每种凭证各司其职：

服务分别存储发布者与批准者状态。登录查看你的发布不会授予运维访问，运维身份也不能以发布者身份批准发布。

Action 行为

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

标准生成工作流提供这些输入。在此显示是为了让你审查生成的文件，而无需推断每个值授权什么：

Action 返回这些输出：

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

故障排除

PACKAGE_PROFILE_REQUIRED

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

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

pnpm exec emdash-plugin profile setup

此检查在服务接受包或 provenance 上传之前运行。

需要公开仓库

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

WORKLOAD_NOT_ALLOWED

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

PROFILE_FETCH_FAILED

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

POLL_TIMEOUT

Action 在工作流批准、发布批准或发布完成之前达到了 timeout-minutes。重新运行前在发布仪表板中检查 intent 状态。同一 GitHub Actions 运行的重新运行会复用其幂等密钥。

撤销自动化发布

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

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

相关文档

• Bundling and publishing 涵盖本地发布与包验证。
• The plugin manifest 定义包元数据与声明的访问。
• Capabilities and security 说明在发布批准与安装期间审查的权限。
• The plugin registry 说明发现、审核与安装验证。