Skip to main content

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

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

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:

  1. Add required permissions to your workflow job:
permissions:
id-token: write
contents: write
attestations: write
  1. 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.

Next steps​

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