Package a plugin

You’ve just built your first plugin, and now you want to share it with the world. In this guide, you’ll learn how to package and share your plugin with others.

For Grafana to be able to load a plugin, it first needs to be built. When you build a plugin from source, a dist directory is created that contains the production build, or plugin assets, for your plugin.

When the Grafana server starts, it recursively looks in the plugin directory for any directory that contains a plugin.json file and tries to load the plugin assets in the same directory.

There are three steps needed to package a plugin:

  • Building the plugin
  • Signing the plugin
  • Archiving the plugin

  1. Build the plugin

    1. yarn install --pure-lockfile
    2. yarn build

  2. (Optional) If your data source plugin has a backend plugin, build it as well.

    1. mage

    make sure that all the binaries are executable and have a 0755 (-rwxr-xr-x) permission

  3. Sign the plugin.

  4. Rename dist directory to match your plugin id and create a ZIP archive

    1. mv dist/ myorg-simple-panel
    2. zip myorg-simple-panel-1.0.0.zip myorg-simple-panel -r

  5. (Optional) Verify your plugin is packaged correctly using zipinfo. It should look like this:

  1. zipinfo grafana-clickhouse-datasource-1.1.2.zip
  3. Archive:  grafana-clickhouse-datasource-1.1.2.zip
  4. Zip file size: 34324077 bytes, number of entries: 22
  5. drwxr-xr-x          0 bx stor 22-Mar-24 23:23 grafana-clickhouse-datasource/
  6. -rw-r--r--       1654 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/CHANGELOG.md
  7. -rw-r--r--      11357 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/LICENSE
  8. -rw-r--r--       2468 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/MANIFEST.txt
  9. -rw-r--r--       8678 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/README.md
  10. drwxr-xr-x          0 bx stor 22-Mar-24 23:23 grafana-clickhouse-datasource/dashboards/
  11. -rw-r--r--      42973 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/dashboards/cluster-analysis.json
  12. -rw-r--r--      56759 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/dashboards/data-analysis.json
  13. -rw-r--r--      39406 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/dashboards/query-analysis.json
  14. -rwxr-xr-x   16469136 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/gpx_clickhouse_darwin_amd64
  15. -rwxr-xr-x   16397666 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/gpx_clickhouse_darwin_arm64
  16. -rwxr-xr-x   14942208 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/gpx_clickhouse_linux_amd64
  17. -rwxr-xr-x   14155776 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/gpx_clickhouse_linux_arm
  18. -rwxr-xr-x   14548992 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/gpx_clickhouse_linux_arm64
  19. -rwxr-xr-x   15209472 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/gpx_clickhouse_windows_amd64.exe
  20. drwxr-xr-x          0 bx stor 22-Mar-24 23:23 grafana-clickhouse-datasource/img/
  21. -rw-r--r--        304 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/img/logo.png
  22. -rw-r--r--       1587 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/img/logo.svg
  23. -rw-r--r--     138400 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/module.js
  24. -rw-r--r--        808 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/module.js.LICENSE.txt
  25. -rw-r--r--     487395 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/module.js.map
  26. -rw-r--r--       1616 bX defN 22-Mar-24 23:23 grafana-clickhouse-datasource/plugin.json
  27. 22 files, 92516655 bytes uncompressed, 34319591 bytes compressed:  62.9%

Publish your plugin on Grafana.com

The best way to share your plugin with the world is to publish it on Grafana Plugins. By having your plugin published on Grafana.com, more users will be able to discover your plugin.

Before you submit your plugin, we ask that you read our guidelines and frequently asked questions.

Guidelines

To speed up the time it takes to review your plugin:

Frequently Asked Questions

Do I need to submit a private plugin?

  • No. Please only submit plugins that you wish to make publicly available for the Grafana community.

How long does it take to review my submission?

  • We’re not able to give an estimate at this time, though we’re constantly working on improving the time it takes to review a plugin.

Publishing your plugin for the first time

Package a plugin - 图1

  1. Sign in to your Grafana Cloud account.
  2. In the left menu, under Org settings, click My Plugins.
  3. Click Submit Plugin.
  4. Enter the information requested by the form.
    • OS & Architecture:
      • Select Single if your plugin archive contains binaries for multiple architectures.
      • Select Multiple if you’d like to submit separate plugin archives for each architecture. This can lead to faster downloads since users can select the specific architecture on which they want to install the plugin.
    • URL: A URL that points to a ZIP archive of your packaged plugin.
    • MD5: The MD5 hash of the plugin specified by the URL.
    • The remaining questions help us determine the signature level for your plugin.
  5. Click Submit. After you have submitted your plugin, we run an automated validation to make sure it adheres to our guidelines. Once your submission passes the validation, it’s placed in a review queue.

All submissions are manually inspected by a plugin reviewer. For every new plugin, we perform a manual review that includes the following checks:

  • Code review: For quality and security purposes, we review the source code for the plugin. If you’re unable to make the source code publicly available, let us know in a comment on your plugin submission.
  • Tests: We install your plugin on one of our Grafana instances to test it for basic use. For more advanced plugins, we may ask you to assist us in configuring a test environment for the plugin. This test environment will be used whenever you submit an plugin update.

Maintain your plugin

To submit an update for an already published plugin:

  1. Sign in to your Grafana Cloud account.
  2. In the left menu, under Org settings, click My Plugins.
  3. Click Submit Update for the plugin you want to update.
  4. Enter the information requested by the form.
    • OS & Architecture:
      • Select Single if your plugin archive contains binaries for multiple architectures.
      • Select Multiple if you’d like to submit separate plugin archives for each architecture. This can lead to faster downloads since users can select the specific architecture they want to install the plugin on.
    • URL: A URL that points to a ZIP archive of your packaged plugin.
    • MD5: The MD5 hash of the plugin specified by the URL.
  5. Click Submit.