Plugin publishing best practices
When publishing a Grafana plugin, follow best practices to ensure a smooth submission, review process, and a higher quality experience for users. Whether you’re fine-tuning your plugin’s functionality or preparing your documentation, by following established guidelines you improve the plugin’s performance, security, and discoverability within the Grafana ecosystem. The recommendations in this document will help you avoid common pitfalls, streamline the review process, and create a plugin that integrates seamlessly into users' workflows.
Before you begin​
Before you proceed make sure you've done the following:
- Created your initial plugin
- Reviewed the best practices for plugin development guide
- Familiarized yourself with the plugin signature levels
Populate your plugin's metadata​
Use metadata to make your Grafana plugin discoverable and user-friendly. Properly structuring the metadata in your plugin.json file not only helps users find your plugin in Grafana’s plugin catalog but also provides essential details about the plugin’s functionality and compatibility.
Focus on these key elements:
name
The name of your plugin must be clear, concise, and descriptive. It's the first point of interaction for potential users, so avoid overly generic or cryptic names. Aim for a name that reflects the plugin’s primary functionality and makes it easy to understand its purpose at a glance.
info.description
The description field summarizes what your plugin does and why users should install it. Limit the description to two sentences, highlighting the core functionality and use cases. A well-written description not only informs users, but also contributes to better search results in the catalog.
info.keywords
Keywords improve the searchability of your plugin within Grafana’s catalog. Choose terms that accurately describe your plugin’s functionality and data types it supports, such as "JSON", "SQL", or "visualization".
Avoid keyword stuffing. Irrelevant keywords are flagged during the review process, potentially delaying publication.
info.logos
Adding logos improves the overall look and feel of your plugin in the plugin catalog, and adds legitimacy and professionalism to your plugin.
info.screenshots
Use the screenshots field to provide an array with one or more screenshot images to be displayed in the plugin catalog. Images give users a visual representation of your plugin, and can help them decide if you plugin solves their problem before installing it.
Make sure that your screenshots:
- Show your plugin in action, highlighting its standout features
- Have a suitable resolution and file type, for example png, jpeg, or gif
info.links
The sponsorship link provides a way for users to support your work and contribute to its development. It appears in the "Links" section of your plugin's detail page and supports various funding platforms, such as GitHub Sponsors or Patreon.
Example:
{
info: {
links: [
{
name: "sponsorship",
url: "https://github.com/sponsors/pluginDeveloper"
}
]
}
}
dependencies.grafanaDependency
Specify the minimum Grafana version your plugin is compatible with so that users running different versions of Grafana know whether your plugin will work for them. Be sure to run end-to-end tests to confirm compatibility with releases you support.
Create a comprehensive README​
Your plugin's README file serves as both a first impression and a detailed guide for your users. It's a combination of a storefront advertisement and an instruction manual—showing what your plugin can do, how to install it, and how users can make the most of it within their Grafana instances.
Use the README template, included as part of the plugin structure generated by the create-plugin tool, to provide your users with everything they need to confidently use and contribute to your plugin.
The template covers the essential components, and you can add more specific details to help users understand the value and functionality of your plugin, such as:
- Screenshots or screen captures: Include screenshots or even video demonstrations so users can quickly grasp the plugin’s capabilities and setup process, giving them confidence to use it effectively.
- Dynamic badges: Badges provide quick information about your plugin, such as the latest release version or whether it has passed security and code checks. Use tools like shields.io with the Grafana.com API to automatically update these badges whenever you publish a new version, adding transparency and trustworthiness to your plugin.
- Contribution guidance: Maintaining a plugin can be demanding, especially for individual developers. Clearly outline how users can provide feedback and report bugs, and direct potential code contributors to your
contributing.md. This fosters community involvement and makes it easier to maintain and improve your plugin over time.
Maintain a detailed changelog​
A well-maintained changelog is essential for plugin transparency and helps users understand what's changed between versions. Grafana displays your changelog in the plugin details page so users can evaluate whether to update.
Use Grafana's automated changelog generation feature to simplify the process of maintaining your changelog. Learn how in the Automatically Generate Changelogs guide.
Changelog best practices​
Use a dedicated CHANGELOG.md file in your repository root with the following information:
- Follow semantic versioning (MAJOR.MINOR.PATCH) and organize entries by version
- Date each release to provide chronological context
- Group changes by type such as "Features", "Bug Fixes", "Breaking Changes"...
- Reference pull requests with links to provide additional context
- Highlight breaking changes prominently to alert users of required actions
Example​
### [1.10.0](https://github.com/user/plugin-name/tree/1.10.0) (2025-04-05)
**Implemented enhancements:**
- Add support for dark theme [\#138](https://github.com/user/plugin-name/pull/138) ([username](https://github.com/username))
- Add ability to customize tooltip formats [\#135](https://github.com/user/plugin-name/pull/135) ([username](https://github.com/username))
- Support for PostgreSQL data source [\#129](https://github.com/user/plugin-name/pull/129) ([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 inconsistent time zone handling [\#134](https://github.com/user/plugin-name/pull/134) ([username](https://github.com/username))
**Closed issues:**
- Documentation needs examples for PostgreSQL queries [\#130](https://github.com/user/plugin-name/issues/130)
**Merged pull requests:**
- Update dependencies to address security vulnerabilities [\#140](https://github.com/user/plugin-name/pull/140) ([username](https://github.com/username))
**Breaking changes:**
- Migrate configuration storage format [\#115](https://github.com/user/plugin-name/pull/115) ([username](https://github.com/username))
With this format your changelog becomes a transparent resource that clearly communicates changes, acknowledges contributions, and provides links to more detailed information. It helps users make informed decisions about updating your plugin and demonstrates your commitment to maintaining a high-quality Grafana plugin.
End-to-end testing​
End-to-end (E2E) testing ensures that your Grafana plugin works correctly across various environments and supported Grafana versions. It replicates real-world usage by testing the plugin in an environment similar to the end-user's setup. Implementing E2E tests helps catch issues before submission, saving time during the review process and ensuring a smoother user experience.
Key points:
- Test compatibility across versions: Ensure your plugin works seamlessly with various versions of Grafana by setting up E2E tests targeting multiple releases.
- Automate testing: Integrate E2E testing into your continuous integration (CI) pipeline to catch issues early and frequently, reducing potential problems during review.
For a comprehensive guide on setting up E2E tests, refer to our E2E test a plugin documentation.
Validate your plugin​
Before submitting your plugin for review, use the Plugin Validator to check for potential issues that could prevent your plugin from being accepted, such as security vulnerabilities or structural problems.
Key points:
- Run locally or in CI: You can run the validator locally or integrate it into your CI workflow to automate the validation process. Note, the validator runs automatically during the default release workflow.
- Validation reports: The tool generates a report, highlighting any errors or warnings that need to be addressed before submission.
For more information on using the validator refer to the Plugin Validator documentation.
Provide a provisioned test environment​
Provisioning a test environment for your plugin can significantly reduce the review time and make it easier for others to test and contribute to your plugin. A provisioned environment includes a pre-configured Grafana instance with sample dashboards and data sources that demonstrate your plugin's functionality.
Key points:
- Why provisioning matters: It ensures that both reviewers and contributors can quickly verify your plugin's behaviour without manual setup, speeding up the review and collaboration process.
- Automated setup: You can provision test environments using Docker to create an out-of-the-box experience that replicates a typical Grafana setup.
To learn more about setting up provisioned environments, check out our provisioning guide.
Automate releases with GitHub Actions​
To streamline your plugin development workflow, automate releases using GitHub Actions. This ensures that your plugin is built, signed, and packaged correctly on each release, reducing human error and expediting the publishing process.
Key points:
- Continuous integration (CI): Use GitHub Actions to automatically build and test your plugin on every commit or pull request, catching issues early.
- Release workflow: Automate the signing and packaging of your plugin when you're ready to publish, ensuring it meets the necessary criteria for submission to the Grafana plugin catalog.
For more details refer to Grafana's Automate packaging and signing with GitHub guide.
Next steps​
Follow these best practices to increase the chances of a successful plugin submission. They are designed to ensure that your plugin not only passes our review process but also delivers an exceptional experience for users. Adopting these practices will streamline your workflow and help create plugins that stand out in the Grafana ecosystem.
Once your plugin is ready to be published follow our guide for submitting your plugin for review. We look forward to seeing what you create!