6 tips to improve your Grafana plugin before you publish
Whether they help you tap into external data sources or add a new visualization type to your dashboard, plugins are a powerful way to customize and extend the value of Grafana.
There’s a rich (and constantly evolving) ecosystem of Grafana plugins you can choose from today. While some of these plugins are created and maintained by the Grafana Labs team, many of them are contributed by our commercial partners and community members.
First, we’d like to thank all of those partners and community members who’ve developed, or are in the process of developing, a plugin for our platform. You’re a huge part of what makes Grafana a truly open and extensible observability platform.
Second, we want to provide some guidance to make it easier than ever for you to publish a plugin to our catalog. If you’re putting the final touches on your plugin before submitting it to us for review and publication, you’ve come to the right place.
In this blog post, we offer six important tips to help you prepare your plugin for our review process, get it published, and make it discoverable by the millions of Grafana users across the globe.
Note: This post assumes you already have some knowledge of the different types of Grafana plugins and how to build one. If you’re looking to learn more about how to create your first plugin, we suggest reading our Get started guide and our Introduction to plugin development pages.
Tip 1: Build a comprehensive README file
Think about how long it should take someone who’s installed your plugin to get from zero to “aha!” You want to make sure users have all the information they need to configure and start using your plugin as efficiently as possible.
Much of this is achieved via a well-written README, which is basically like a shop window into your plugin. We offer plugin developers this README template, generated by the create-plugin tool, so they know exactly what kind of information to include.
In addition to a basic overview of your plugin, its use cases, and core requirements for running it, here are some items we suggest including in your README file on GitHub:
- Screenshots (or even videos): Sometimes, the best way to help somebody get started with your plugin is to show them, rather than tell them, what they need to know. While it’s not a requirement, including screenshots and even links to YouTube videos within your README is a great way to visually walk users through the capabilities of your plugin and help them ramp up more quickly.
- Dynamic badges: Badges are a popular way to provide useful information, at a glance, to anyone browsing your README (these badges are also visible in the Grafana plugin catalog). For example, a badge can convey the latest version of your plugin, how many downloads your plugin has, or that your plugin has passed certain code and security checks — something that can also help build trust with potential users. You can use the generator on Shields.io, together with the Grafana.com API, to create dynamic badges that update automatically when you publish a new version of your plugin to the marketplace.
- Info on how to contribute: It’s always a good idea to offer a clear avenue for users to provide feedback, report bugs, and collaborate with you on your plugin. In your README, let users know where and how to reach out.
Tip 2: Add metadata to improve discoverability
The plugin.json file defines important metadata about your plugin, including its display name, description, and other important components that will influence how users find your plugin.
Some important properties within the plugin.json file to consider as part of publishing include:
name: This is the human-readable name of the plugin that is displayed to the user in the catalog. Try to pick something logical!description: This allows you to display a summary of what your plugin is for and why someone should use it. Aim for no more than two sentences.keywords: These allow you to optimize for search terms in the catalog to make your plugin more discoverable. For example, if your plugin works with JSON data, include JSON within your keywords, so it’s more likely to be found by users searching that term. We do check for relevancy in our review, though, so no overloading, please!
To learn more about the plugin.json file, check out our developer documentation.
Tip 3: Declare which versions of Grafana your plugin works with (and test against them)
The plugin.json file also allows you to specify the minimum required version of Grafana for your plugin to be installable, as your grafanaDependency. The recently released plugin-e2e library allows you to easily create end-to-end tests that target multiple Grafana releases, and run these as part of your CI process to continuously verify that your plugin works against these releases.
Tip 4: Use provisioning to provide a test environment
Full transparency: it’s difficult for us to provide plugin developers with a concrete timeline, in terms of how long our review process will take prior to publication. That said, there are steps you can take to help reduce the cycle time — and using provisioning to provide a test environment is a big one.
Provisioning entails preparing and configuring a test environment within your plugin’s Docker development environment. These test environments are critical for us to verify a plugin’s behavior and that it works as intended, and if you provision your plugin prior to submission, your review period will always be shorter.
But there are other benefits to provisioning, too. These include:
- Encouraging contributions: An out-of-the-box testing environment makes it easier for community members and potential contributors to your plugin to experiment with new features or raise pull requests.
- Easier setup for end-to-end tests: By provisioning sample dashboards as part of your testing environment, you’re primed to run end-to-end tests against specific scenarios across local development and in CI pipelines.
- Improved clarity: In general, provisioned plugins make it easier for tech-savvy users to understand how the plugin works. If the user is a developer, for instance, they might reference the provisioning file to understand exactly how the plugin is configured and look at sample dashboards.
To learn more about provisioning your plugin, visit our developer documentation.
Tip 5: Validate your plugin
You can run our plugin validator tool on your local machine, or in your CI workflow, to generate a report of any security or structural issues that might prevent your plugin from getting published. The tool runs a series of analyzers to ensure your plugin follows certain best practices and meets our requirements related to publishing.
The easiest way to run the tool is using the Docker image, as it requires all the necessary dependencies. For example:
docker run --pull=always grafana/plugin-validator-cli -sourceCodeUri https://github.com/grafana/clock-panel/tree/v2.1.2 https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zipSee our GitHub repo for full usage instructions.
Note: If you’re using the GitHub workflows discussed in the next tip, you’ll already validate your plugin as part of your release.
Tip 6: Use GitHub Actions to automate your releases
In order to publish your plugin to the catalog, you need to build, sign, and package the plugin for publication. Incorrectly packaged plugins is one of the most common issues we catch when a plugin is submitted for publication.
If your plugin is available on GitHub, be sure to add the GitHub Actions workflows for plugin development to your repository. This CI workflow helps you catch mistakes early by building and testing your plugin on every commit.
When you’re ready to publish your plugin, use the release workflow to sign, package, and lint your plugin before submitting it for review. The workflow drafts a GitHub release, with the signed and packaged plugin as release assets. The release workflow even lints the plugin using the plugin validator tool mentioned above.
Next steps
When you’ve checked all the boxes above and are ready for your plugin to be published, simply head over to your Grafana Cloud account and submit your plugin for review.
If you want to learn about other ways to improve your plugin, be sure to check out the Grafana developer portal and plugin examples on GitHub. And if you have any questions about the development or publishing process, please feel free to reach out in our community forum.
Editor’s note: This blog post was originally written by Marcus Olsson, a former developer advocate at Grafana Labs, in January 2021. It was updated in June 2024 to reflect more recent best practices for publishing a Grafana plugin.
