使用 GitHub CI 自动化打包和签署

我们建议设置您的插件以使用 Github 工作流从 create-plugin 生成，以确保您的插件将以正确的格式构建和打包。

此外，我们建议使用此工作流生成的 zip 文件来测试插件。

如果在您的 Github 仓库 secrets 中包含 Grafana 访问策略令牌 (Access Policy Token)，将自动创建一个已签署的构建，您可以在提交之前使用它在本地测试插件。签署插件文档包含有关如何创建此令牌的指南。

通过创建发布标签，整个过程将实现自动化，生成一个 zip 文件，您可以提交该文件以发布到 Grafana 插件目录

您可以使用发布页面上的归档文件和 zip 文件链接来提交您的插件。

设置发布工作流

确保您的仓库包含一个名为 .github/workflows/release.yml 的文件，其内容如下

.github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*' # Run workflow on version tags, e.g. v1.0.0.

jobs:
  release:
    permissions:
      id-token: write
      contents: write
      attestations: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: grafana/plugin-actions/build-plugin@main
        with:
          # see https://grafana.org.cn/developers/plugin-tools/publish-a-plugin/sign-a-plugin#generate-an-access-policy-token to generate it
          # save the value in your repository secrets
          policy_token: ${{ secrets.GRAFANA_ACCESS_POLICY_TOKEN }}
          # creates a signed build provenance attestation to verify the authenticity of the plugin build
          attestation: true

如何触发发布工作流

要触发发布工作流，您需要向仓库推送一个格式为 vX.X.X 的标签。通常，您的所有更改将合并到 main 分支，并将标签应用于 main

使用您的包管理器创建 `vX.X.X` 标签（推荐）

创建版本标签最简单的方法是使用您的包管理器。

在以下示例中，创建了一个补丁版本（遵循语义化版本控制）

使用 npm

npm version patch

使用 yarn

yarn version patch

使用 pnpm

pnpm version patch

这会更新您在 package.json 文件中的版本，并创建一个格式为 vX.X.X 的新 Git 标签。如果您想创建新的次版本或主版本，可以将 patch 更改为 minor 或 major。

创建标签后，将其推送到仓库

git push origin main --follow-tags

在 Github 中发布您的版本

在您创建并推送标签后，发布工作流将运行，生成包含将插件提交到 Grafana 插件目录所需的所有 artifact（构件）的版本。

工作流会创建一个 草稿版本。您可以在 GitHub 中编辑该版本，根据需要更新描述，然后发布它。有关管理仓库版本的更多详细信息，请参阅 GitHub 文档。

使用您的发布资产提交插件

草稿版本发布后，您可以使用发布资产将插件提交到 Grafana 插件目录。只需复制归档（zip）文件和 sha1 校验和的链接。在插件提交表单中使用这些信息。

下载发布 zip 文件

直接从 GitHub 仓库发布路径访问发布 zip 文件（例如，https://github.com/org/plugin-id/releases）。

自动签署您的插件

您可以使用 Github Action 签署您的插件版本。首先，您需要生成访问策略令牌并将其保存在您的仓库 secrets 中。

将您的访问策略令牌保存为 GRAFANA_ACCESS_POLICY_TOKEN。

默认情况下，create-plugin 会向您的脚手架插件添加以下 release.yml 文件，内容如下。如果您的插件仓库中缺少此文件，请复制以下内容以添加工作流

.github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*' # Run workflow on version tags, e.g. v1.0.0.

jobs:
  release:
    permissions:
      id-token: write
      contents: write
      attestations: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: grafana/plugin-actions/build-plugin@main
        with:
          # see https://grafana.org.cn/developers/plugin-tools/publish-a-plugin/sign-a-plugin#generate-an-access-policy-token to generate it
          # save the value in your repository secrets
          policy_token: ${{ secrets.GRAFANA_ACCESS_POLICY_TOKEN }}
          attestation: true
          use_changelog_generator: true # Enable automatic changelog generation

然后，按照常规流程触发发布工作流。您的插件将自动签署，您可以使用发布的资产来提交插件。

插件构建的来源证明

来源证明 (Provenance attestation) 是一项可生成构建来源和过程的可验证记录的功能，可增强插件构建的安全性。此功能允许用户确认他们正在安装的插件是通过您的官方构建流水线创建的。

目前，此功能仅在公共仓库的 GitHub Actions 中可用。虽然我们推荐使用带有来源证明的 GitHub Actions 以提高安全性，但您仍然可以使用其他 CI/CD 平台或手动方法构建和分发插件。

启用来源证明

要在现有 GitHub Actions 工作流中启用来源证明

为您的工作流作业添加所需权限

permissions:
  id-token: write
  contents: write
  attestations: write

在 build-plugin action 中启用证明

- uses: grafana/plugin-actions/build-plugin@main
  with:
    policy_token: ${{ secrets.GRAFANA_ACCESS_POLICY_TOKEN }}
    attestation: true

工作流在构建插件 zip 文件时将自动生成证明。

来源证明故障排除

如果在插件验证器或插件提交中遇到以下错误

"没有来源证明。此插件是在没有构建验证的情况下构建的。"
"无法验证插件构建。"

按照上述步骤在您的 GitHub Actions 工作流中启用来源证明。

自动生成变更日志

维护详细的变更日志对于向用户传达更新至关重要，并且会在 Grafana 插件详情页面中突出显示。为了简化此过程，我们的插件构建工作流支持自动生成变更日志。

使用 GitHub Actions 工作流生成变更日志

build-plugin GitHub Action 可以使用 github-changelog-generator 工具自动生成和维护您的插件变更日志。此功能

创建按版本组织的详细 CHANGELOG.md 文件
按类型（功能、错误修复等）对更改进行分组
包含指向拉取请求和议题的链接
致谢贡献者
将更新的变更日志提交到您的仓库

要在工作流中启用自动生成变更日志，请向 build-plugin action 添加参数 use_changelog_generator: true

- uses: grafana/plugin-actions/build-plugin@main
  with:
    policy_token: ${{ secrets.GRAFANA_ACCESS_POLICY_TOKEN }}
    attestation: true
    use_changelog_generator: true # Enable automatic changelog generation

要求

要使用此功能，请确保您的工作流具有必要的权限

permissions:
  contents: write

变更日志生成器需要写入权限才能将更新的 CHANGELOG.md 文件提交到您的仓库。

如果您的目标分支受保护，默认的 github.token 即使具有写入权限也无法直接推送更改。在这种情况下，您需要

创建一个具有适当权限的个人访问令牌 (PAT)
将其存储为仓库 secret（例如，CHANGELOG_PAT）
配置 action 以使用此令牌

- name: Build plugin
  uses: grafana/plugin-actions/build-plugin@main
  with:
    use_changelog_generator: true
    token: ${{ secrets.CHANGELOG_PAT }} # Replace default github.token

生成的变更日志格式

生成的变更日志遵循标准化格式，明确分类更改

## [1.2.0](https://github.com/user/plugin-name/tree/1.2.0) (2025-03-15)

**Implemented enhancements:**

- Add dark theme support [\#138](https://github.com/user/plugin-name/pull/138) ([username](https://github.com/username))
- Add tooltip customization options [\#135](https://github.com/user/plugin-name/pull/135) ([username](https://github.com/username))

**Fixed bugs:**

- Fix panel crash when switching dashboards [\#139](https://github.com/user/plugin-name/pull/139) ([username](https://github.com/username))
- Fix time zone handling inconsistencies [\#134](https://github.com/user/plugin-name/pull/134) ([username](https://github.com/username))

**Closed issues:**

- Documentation needs more examples [\#130](https://github.com/user/plugin-name/issues/130)

**Merged pull requests:**

- Update dependencies for security [\#140](https://github.com/user/plugin-name/pull/140) ([username](https://github.com/username))

后续步骤

打包插件后，继续发布插件或安装打包好的插件。

设置发布工作流​

如何触发发布工作流​

使用您的包管理器创建 vX.X.X 标签（推荐）​

在 Github 中发布您的版本​

使用您的发布资产提交插件​

下载发布 zip 文件​

自动签署您的插件​

插件构建的来源证明​

启用来源证明​

来源证明故障排除​

自动生成变更日志​

使用 GitHub Actions 工作流生成变更日志​

要求​

生成的变更日志格式​

后续步骤​