@grafana/plugin-validator

中文文档
0.53.9发布于 2026/11/16Apache-2.0CommonJS构建来源已验证近 30 天下载 5959

Grafana Plugin Validator

原始使用文档
文档目录18 节
  1. Installation and usage
  2. Docker (recommended)
  3. NPX
  4. Locally
  5. MCP Server (for AI assistants)
  6. Generating local files For validation
  7. Options
  8. Using a configuration file
  9. Source code
  10. Supported remote Git services
  11. Debug mode
  12. LLM provider configuration
  13. Security tools
  14. Analyzers
  15. Output
  16. Severity
  17. Getting Help
  18. License

Grafana Plugin Validator

License Go Report Card

This tool helps speed up the process of publishing plugins to Grafana.com. It runs a series of analyzers to ensure plugins are following best practices, checking for security and structural issues, as well as specific requirements related to publishing. A general overview of these requirements can be found here: https://grafana.com/docs/grafana/latest/developers/plugins/publishing-and-signing-criteria/.

It requires a path to a remote or local ZIP archive of the plugin to be specified, for example:

  • Remote: https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zip
  • Local: file://Users/me/Downloads/grafana-clock-panel-2.1.2.zip

You can additionally provide a link to the source code for the project with -sourceCodeUri to enable additional analyzers such as the Vulnerability Scan.

Installation and usage

Ensure that your version of Go matches the one specified in the go.mod file to avoid compatibility issues

It is easiest to run the tool using the Docker image as it contains all the security scanning tools needed for the full set of analyzers - so you don't need to have these additional tools installed on your system.

docker run --pull=always grafana/plugin-validator-cli [options] [http://yourdomain/plugin_archive.zip]

Example 1 (basic)

docker run --pull=always grafana/plugin-validator-cli https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zip

Example 2 (specifying source code location)

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.zip

Using a local archive file with Docker

To run the tool with a local archive you will need to mount it as a docker volume. Here's an example:

docker run --pull=always -v /path/to/plugin_archive.zip:/archive.zip grafana/plugin-validator-cli /archive.zip

[!NOTE] If using relative paths your path must start with ./

Using a local archive file and local source code

docker run --pull=always -v /path/to/plugin_archive.zip:/archive.zip -v /path/to/source_code:/source_code grafana/plugin-validator-cli -sourceCodeUri file:///source_code /archive.zip

[!NOTE] If using relative paths your path must start with ./

NPX

npx -y @grafana/plugin-validator@latest -sourceCodeUri [options] [path/to/plugin_archive.zip]

Locally

First you must compile and install it:

git clone [email protected]:grafana/plugin-validator.git
cd plugin-validator/pkg/cmd/plugincheck2
go install

Then you can run the utility:

plugincheck2 -sourceCodeUri [source_code_location/] [plugin_archive.zip]

MCP Server (for AI assistants)

The plugin validator can be used as an MCP (Model Context Protocol) server, allowing AI assistants like Claude, Cline, and other MCP-compatible tools to validate Grafana plugins.

See the MCP Server README for configuration instructions.

Generating local files For validation

You must create a .zip archive containing the dist/ directory but named as your plugin ID:

PLUGIN_ID=$(grep '"id"' < src/plugin.json | sed -E 's/.*"id" *: *"(.*)".*/\1/')
cp -r dist "${PLUGIN_ID}"
zip -qr "${PLUGIN_ID}.zip" "${PLUGIN_ID}"
npx @grafana/plugin-validator@latest -sourceCodeUri file://. "${PLUGIN_ID}.zip"

You can optionally remove the files that were generated:

rm -r "${PLUGIN_ID}" "${PLUGIN_ID}.zip"

Options

Additional options can be passed to the tool:

❯ plugincheck2 -help
Usage plugincheck2:
  -config string (optional)
        Path to configuration file
  -sourceCodeUri string (optional)
        URI to the source code of the plugin. If set, the source code will be downloaded and analyzed. This can be a ZIP file URL, a URL to git repository or a local file (starting with `file://`)
  -strict (optional)
        If set, plugincheck returns non-zero exit code for warnings
  -checksum string (optional)
        If set, the checksum of the plugin archive will be checked against this value. MD5 and SHA256 are supported.
  -analyzer string (optional)
        If set, only an specific analyzer and it's dependencies will run.
  -severity string (optional)
        If used, it will set the severity of the analyzer (it has the highest priority).

Using a configuration file

You can pass a configuration YAML file to the validator with the -config option. Several configuration examples are available to use here: https://github.com/grafana/plugin-validator/tree/main/config.

Enabling and disabling analyzers via config

If you want to disable an specific check (analyzer) you can define this in your configuration file, adding an analyzers section, and specifying which analyzer or analyzer rules to enable and disable.

For example, disable the version analyzer:

global:
  enabled: true
  jsonOutput: false
  reportAll: false

analyzers:
  version:
    enabled: false

You can also disable specific rules or change their severity level:

global:
  enabled: true
  jsonOutput: false
  reportAll: false

analyzers:
  readme:
    rules:
      missing-readme:
        enabled: true
        severity: warning

Severity levels could be: error, warning, or ok.

Some rules are disabled by default and only run when their analyzer or rule configuration sets enabled: true.

Note: Grafana Labs enforces its own configuration for plugins submissions and your own config file can't change these rules.

Excluding a plugin from an analyzer or rule

It's also possible to exclude a specific plugin from an analyzer or a specific rule within an analyzer. This is useful when a particular check is not applicable to your plugin.

To disable an entire analyzer for a plugin, add an exceptions list with the plugin ID.

analyzers:
  some-analyzer:
    enabled: true
    # This entire analyzer will be skipped for 'my-plugin-id'
    exceptions:
      - my-plugin-id

To disable a single rule for a plugin, add the exceptions list to the rule's configuration.

analyzers:
  some-analyzer:
    rules:
      some-rule:
        enabled: true
        # This rule will be skipped for 'my-plugin-id'
        exceptions:
          - my-plugin-id

Source code

You can specify the location of the plugin source code to the validator with the -sourceCodeUri option. Doing so allows for additional analyzers to be run and for a more complete scan.

Supported remote Git services

The following public Git services are supported:

  • GitHub
  • GitLab
  • Bitbucket

Private repositories are not currently supported.

Make sure to include the ref (branch or tag) of the corresponding source code.

For example: you are validating version v2.1.2 and your project is in GitHub. Make sure you create a corresponding tag or branch and use the URL https://github.com/grafana/clock-panel/tree/v2.1.2.

Debug mode

You can run the validator in debug mode to get more information about the running checks and possible errors.

Docker:

docker run --pull=always -e DEBUG=1 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.zip

NPX:

DEBUG=1 npx -y @grafana/plugin-validator@latest -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.zip

Locally:

DEBUG=1 plugincheck2 -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.zip

LLM provider configuration

The llmreview and codediff analyzers use an LLM to review plugin source code. Three providers are supported: Anthropic, OpenAI, and Google (Gemini).

Set one of the following environment variables to enable LLM-based analysis. The first key found (in the order below) is used:

Environment VariableProviderDefault Model
ANTHROPIC_API_KEYAnthropicclaude-opus-4-6
OPENAI_API_KEYOpenAIgpt-5.4
GEMINI_API_KEYGooglegemini-3.1-flash-lite-preview

Example:

ANTHROPIC_API_KEY=sk-ant-... plugincheck2 -sourceCodeUri https://github.com/org/repo/tree/v1.0.0 plugin.zip

You can skip individual LLM analyzers with SKIP_LLM_REVIEW=1 or SKIP_LLM_CODEDIFF=1.

Security tools

This validator makes uses of the following open source security tools:

If you run the validator locally or via NPX you can benefit from installing these tools in your system to make them part of your validation checks.


Analyzers

The tool runs a series of analyzers to ensure submitted plugins are following best practices, and speed up the process of approving a plugin for publishing, detailed in the table below. The Analyzer column includes the name required for altering the behavior of a given check in a configuration file. The Dependencies column specifies whether the analyzer requires the source code for the plugin to be provided with sourceCodeUri or for any additional security scanning tools to be present.

AnalyzerDescriptionDependencies
Archive Name / archivenameThe name of the archive should be correctly formatted.None
Archive Structure / archiveEnsures the contents of the zip file have the expected layout.None
Backend Binary / backendbinaryValidates the consistency between the existence of a binary file and plugin.json declarations for backend or alerting.None
Backend Debug / backenddebugChecks that the standalone debug files for backend plugins are not present.None
Binary Permissions / binarypermissionsFor datasources and apps with binaries, this ensures the plugin can run when extracted on a system.None
Broken Links / brokenlinksDetects if any URL doesn't resolve to a valid location.None
Build Tags / buildtagsChecks Go backend executables for disallowed build tags.None
Build Tools / buildtoolsChecks that the plugin uses Grafana's standard create-plugin build tooling.None
Changelog (exists) / changelogEnsures a CHANGELOG.md file exists within the zip file.None
Checksum / checksumValidates that the passed checksum (as a validator arg) is the one calculated from the archive file.checksum
Circular Dependencies / circulardependenciesEnsures that there aren't any circular dependencies between plugins (plugin.json, dependencies.plugins field).None
Code Diff / codediffAPI key for one of: Anthropic (ANTHROPIC_API_KEY), OpenAI (OPENAI_API_KEY), or Google (GEMINI_API_KEY)
Code Rules / code-rulesChecks for forbidden access to environment variables, file system or use of syscall module.semgrep, sourceCodeUri
Developer Jargon / jargonGenerally discourages use of code jargon in the documentation.None
Discoverability / discoverabilityWarns about missing keywords and description that are used for plugin indexing in the catalog.None
Go Manifest / go-manifestValidates the build manifest.None
Go Security Checker / go-secInspects source code for security problems by scanning the Go AST.gosec, sourceCodeUri
Go Vulnerability Checker / govulncheckScans Go backend source and plugin backend binaries for known vulnerabilities (govulncheck).govulncheck, sourceCodeUri for source scans
JS Source Map / jsMapChecks for required module.js.map file(s) in archive.sourceCodeUri
Legacy Grafana Toolkit usage / legacybuilderDetects the usage of the not longer supported Grafana Toolkit.None
Legacy Platform / legacyplatformDetects use of Angular which is deprecated.None
License Type / licenseChecks the declared license is one of: BSD, MIT, Apache 2.0, LGPL3, GPL3, AGPL3.None
LLM Review / llmreviewRuns the code through an LLM to check for security issues or disallowed usage.API key for one of: Anthropic (ANTHROPIC_API_KEY), OpenAI (OPENAI_API_KEY), or Google (GEMINI_API_KEY)
Logos / logosDetects whether the plugin includes small and large logos to display in the plugin catalog.None
Manifest (Signing) / manifestWhen a plugin is signed, the zip file will contain a signed MANIFEST.txt file.None
Metadata / metadataChecks that plugin.json exists and is valid.None
Metadata Grafana Dependency / grafanadependencyChecks that dependencies.grafanaDependency in plugin.json is valid.None
Metadata Paths / metadatapathsEnsures all paths are valid and images referenced exist.None
Metadata Validity / metadatavalidEnsures metadata is valid and matches plugin schema.None
module.js (exists) / modulejsAll plugins require a module.js to be loaded.None
Nested includes metadata / includesnestedValidates that nested plugins have the correct metadata.None
Nested Metadata / nestedmetadataRecursively checks that all plugin.json exist and are valid.None
No Tracking Scripts / trackingscriptsDetects if there are any known tracking scripts, which are not allowed.None
Organization (exists) / orgVerifies the org specified in the plugin ID exists.None
package.json / packagejsonEnsures that package.json exists and the version matches the plugin.jsonNone
Plugin Docs / plugindocsRuns the @grafana/plugin-docs-cli validate --dist command to check the multi-page documentation built into the archive (only for plugins that set docsPath in plugin.json).node, npx
Plugin Name formatting / pluginnameValidates the plugin ID used conforms to our naming convention.None
Provenance attestation validation / provenanceValidates the provenance attestation if the plugin was built with a pipeline supporting provenance attestation (e.g Github Actions).None
Published / published-pluginDetects whether any version of this plugin exists in the Grafana plugin catalog currently.None
React 19 Compatibility / reactcompatDetects usage of React APIs removed or deprecated in React 19 using @grafana/react-detect.npx
Readme (exists) / readmeEnsures a README.md file exists within the zip file.None
Required Links / requiredlinksChecks that plugin.json has License, Privacy Policy and Support links with valid https URLs. Disabled by default.None
Restrictive Dependency / restrictivedepSpecifies a valid range of Grafana versions that work with this version of the plugin.None
Safe Links / safelinksChecks that links from plugin.json are safe.None
Screenshots / screenshotsScreenshots are specified in plugin.json that will be used in the Grafana plugin catalog.None
SDK Usage / sdkusageEnsures that grafana-plugin-sdk-go is up-to-date.None
Signature / signatureEnsures the plugin has a valid signature.None
Source Code / sourcecodeA comparison is made between the zip file and the source code to ensure what is released matches the repo associated with it.sourceCodeUri
Type Suffix (panel/app/datasource) / typesuffixEnsures the plugin has a valid type specified.None
Unique README.md / templatereadmeEnsures the plugin doesn't re-use the template from the create-plugin tool.None
Unsafe SVG / unsafesvgChecks if any svg files are safe based on a whitelist of elements and attributes.None
Version / versionEnsures the version submitted is newer than the currently published plugin. If this is a new/unpublished plugin, this is skipped.None
Virus Scan / virusscanRuns a virus scan on the plugin archive and source code using clamscan (clamav).clamscan
Vulnerability Scanner / osv-scannerDetects critical vulnerabilities in Go modules and yarn lock files.osv-scanner, sourceCodeUri

Output

By default, the tool outputs results in plain text as shown below.

Default:

warning: README.md: possible broken link: https://www.d3js.org (404 Not Found)
detail: README.md might contain broken links. Check that all links are valid and publicly accessible.
warning: README.md contains developer jargon: (yarn)
detail: Move any developer and contributor documentation to a separate file and link to it from the README.md. For example, CONTRIBUTING.md, DEVELOPMENT.md, etc.
error: osv-scanner detected a critical severity issue
detail: SEVERITY: CRITICAL in package immer, vulnerable to CVE-2021-23436
error: osv-scanner detected a critical severity issue
detail: SEVERITY: CRITICAL in package json-schema, vulnerable to CVE-2021-3918
error: Plugin version 0.0.9 is invalid.
detail: The submitted plugin version 0.0.9 is not greater than the latest published version 0.0.9 on grafana.com.

This can be changed to JSON by passing a configuration file which includes:

global:
  jsonOutput: true

Resulting in output similar to:

{
  "id": "briangann-gauge-panel",
  "version": "0.0.9",
  "plugin-validator": {
    "brokenlinks": [
      {
        "Severity": "warning",
        "Title": "README.md: possible broken link: https://www.d3js.org (404 Not Found)",
        "Detail": "README.md might contain broken links. Check that all links are valid and publicly accessible.",
        "Name": "broken-link"
      }
    ],
    "jargon": [
      {
        "Severity": "warning",
        "Title": "README.md contains developer jargon: (yarn)",
        "Detail": "Move any developer and contributor documentation to a separate file and link to it from the README.md. For example, CONTRIBUTING.md, DEVELOPMENT.md, etc.",
        "Name": "developer-jargon"
      }
    ],
    "osv-scanner": [
      {
        "Severity": "error",
        "Title": "osv-scanner detected a critical severity issue",
        "Detail": "SEVERITY: CRITICAL in package immer, vulnerable to CVE-2021-23436",
        "Name": "osv-scanner-critical-severity-vulnerabilities-detected"
      },
      {
        "Severity": "error",
        "Title": "osv-scanner detected a critical severity issue",
        "Detail": "SEVERITY: CRITICAL in package json-schema, vulnerable to CVE-2021-3918",
        "Name": "osv-scanner-critical-severity-vulnerabilities-detected"
      },
    ],
    "version": [
      {
        "Severity": "error",
        "Title": "Plugin version 0.0.9 is invalid.",
        "Detail": "The submitted plugin version 0.0.9 is not greater than the latest published version 0.0.9 on grafana.com.",
        "Name": "wrong-plugin-version"
      }
    ]
  }
}

Severity

By default, the tool will show any warning or error level results from the analyzers. To see all results including successes, you can pass a configuration file which includes:

global:
  reportAll: true

Getting Help

License

Grafana Plugin Validator is distributed under the Apache 2.0 License.

版本与发布记录

@grafana/plugin-validator 共发布 137 个版本,首次发布于 2023/03/01;过去 12 个月发布了 69 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.53.9latest2026/11/16今天
0.53.62026/11/115 天前
0.53.52026/11/097 天前
0.53.42026/11/097 天前
0.53.32026/11/0413 天前
0.53.22026/11/0313 天前

关于 @grafana/plugin-validator 的常见问题

@grafana/plugin-validator 是什么?

Grafana Plugin Validator

如何安装 @grafana/plugin-validator?

在项目目录运行 npm install @grafana/plugin-validator,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 plugin-validator,可以用 npx plugin-validator 直接运行。

@grafana/plugin-validator 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/grafana__plugin-validator 是否存在。

@grafana/plugin-validator 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@grafana/plugin-validator 可以商用吗?

@grafana/plugin-validator 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@grafana/plugin-validator 的下载量有多少?

根据 npm 官方下载统计,@grafana/plugin-validator 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,959 次,日均约 199 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@grafana/plugin-validator 还在维护吗?

最新版本 0.53.9 发布于 2026/11/16(今天);至今共发布 137 个版本,其中过去 12 个月发布了 69 个;首次发布于 2023/03/01。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。