Automate packaging and signing with GitHub CI

We recommend setting up your plugin to use the supplied Github workflows from create-plugin to ensure that your plugin will be built and packaged in the correct format.

Additionally, we recommend using the zip file produced from this workflow to test the plugin.

If a Grafana Access Policy Token is included in your Github repository secrets, a signed build is automatically created, which you can use to test the plugin locally before submission. The sign a plugin documentation includes guidance on how to create this token.

By creating a release tag, the whole process becomes automated, resulting in a zip file that you can submit for publication to the Grafana plugin catalog

You can use the links to the archive and zip files from the release page to make your plugin submission.

Setup the release workflow

Ensure your repository contains a .github/workflows/release.yml file with the following contents:

.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.com/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

How to trigger the release workflow

To trigger the release workflow you need to push a tag with the format vX.X.X to the repository. Typically all of your changes will be merged into main, and the tag is applied to main

Create a `vX.X.X` tag with your package manager (Recommended)

The easiest way to create a version tag is using your package manager.

In the following examples a patch version (following Semantic Versioning) is created:

with npm:

npm version patch

with yarn:

yarn version patch

with pnpm:

pnpm version patch

This updates your version in the package.json file and creates a new Git tag with the format vX.X.X. You can change patch to minor or major if you want to create a new minor or major version.

After creating the tag, push it to the repository:

git push origin main --follow-tags

Publish your release in Github

After you create and push the tag, the release workflow will run, generating a release with all the artifacts needed to submit your plugin to the Grafana plugin catalog.

The workflow creates a draft release. You can edit the release in GitHub, update the description as needed, and then publish it. For more details on managing repository releases, refer to the GitHub documentation.

Use your release assets for your plugin submission

Once the draft release is published, you can use the release assets to submit your plugin to the Grafana plugin catalog. Simply copy the links to the archive (zip) file and sha1 sum. Use these in the plugin submission form.

Download the release zip file

Access the release zip file directly from the GitHub repository release path (for example, https://github.com/org/plugin-id/releases).

Signing your plugin automatically

You can sign your plugin releases using the Github Action. First you will have to Generate an Access Policy Token and save it in your repository secrets.

Save your Access Policy Token as GRAFANA_ACCESS_POLICY_TOKEN.

By default, create-plugin will add the following release.yml to your scaffolded plugin with the following contents. If this is missing from your plugin repository, copy the following to add the workflow:

.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.com/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

Then, follow the regular process to trigger the release workflow. Your plugin will be signed automatically, and you can use the release assets for your plugin submission.

Provenance attestation for plugin builds

Provenance attestation, that is, a feature that generating verifiable records of the build's origin and process, enhances the security of your plugin builds. This feature allows users to confirm that the plugin they are installing was created through your official build pipeline.

Currently, this feature is available only with GitHub Actions in public repositories. While we recommend using GitHub Actions with provenance attestation for improved security, you can still build and distribute plugins using other CI/CD platforms or manual methods.

Enable provenance attestation

To enable provenance attestation in your existing GitHub Actions workflow:

Add required permissions to your workflow job:

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

Enable attestation in the build-plugin action:

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

The workflow will generate attestations automatically when building your plugin zip file.

Troubleshoot provenance attestation

If you encounter errors in the plugin validator or your plugin submission like these:

"No provenance attestation. This plugin was built without build verification."
"Cannot verify plugin build."

Follow the steps above to enable provenance attestation in your GitHub Actions workflow.

Automatically Generate Changelogs

Maintaining a detailed changelog is essential for communicating updates to your users and is displayed prominently in the Grafana plugin details page. To simplify this process, our plugin build workflow supports automatic changelog generation.

Using the GitHub Actions Workflow for Changelog Generation

The build-plugin GitHub Action can automatically generate and maintain your plugin's changelog using the github-changelog-generator tool. This feature:

Creates a comprehensive CHANGELOG.md file organized by release
Groups changes by type (features, bug fixes, etc.)
Includes links to pull requests and issues
Acknowledges contributors
Commits the updated changelog to your repository

To enable automatic changelog generation in your workflow, add the use_changelog_generator: true parameter to your build-plugin action:

- 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

Requirements

To use this feature, ensure your workflow has the necessary permissions:

permissions:
  contents: write

The changelog generator requires write access to commit the updated CHANGELOG.md file to your repository.

If your target branch is protected, the default github.token cannot push changes directly, even with write permissions. In this case, you need to:

Create a Personal Access Token (PAT) with appropriate permissions
Store it as a repository secret (e.g., CHANGELOG_PAT)
Configure the action to use this token:

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

Generated Changelog Format

The generated changelog follows a standardized format that clearly categorizes changes:

## [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))

Next steps

When you've packaged your plugin, proceed to publishing a plugin or installing a packaged plugin.

Setup the release workflow​

How to trigger the release workflow​

Create a vX.X.X tag with your package manager (Recommended)​

Publish your release in Github​

Use your release assets for your plugin submission​

Download the release zip file​

Signing your plugin automatically​

Provenance attestation for plugin builds​

Enable provenance attestation​

Troubleshoot provenance attestation​

Automatically Generate Changelogs​

Using the GitHub Actions Workflow for Changelog Generation​

Requirements​

Generated Changelog Format​

Next steps​