Buildkite Plugin Linter 镜像文档

镜像概述

Buildkite Plugin Linter 是一款针对 Buildkite 插件的自动化检查工具（Linter），旨在帮助开发者验证插件的结构规范性、语法正确性及最佳实践遵循情况，确保插件符合 Buildkite 平台的集成标准和质量要求。

主要用途

• 检查 Buildkite 插件的配置文件（如 plugin.yml）结构与语法
• 验证插件元数据（如名称、版本、描述）的完整性与格式
• 强制遵循 Buildkite 插件开发最佳实践（如安全规范、兼容性要求）
• 自动化插件质量检查，减少人工审核成本

核心功能与特性

• 结构验证：检查插件目录结构是否符合 Buildkite 规范（如必需文件、目录层级）
• 语法检查：验证 YAML/JSON 配置文件（如 plugin.yml、hooks/ 脚本）的语法正确性
• 元数据校验：确保插件元数据（名称、版本、作者、描述等）符合必填项与格式要求
• 最佳实践检测：内置 Buildkite 插件开发最佳实践规则（如避免硬编码敏感信息、钩子脚本安全性）
• 版本兼容性：验证插件声明的支持版本与 Buildkite 平台版本的兼容性
• 多输出格式：支持文本、JSON 等输出格式，便于集成到 CI/CD 报告系统

使用场景与适用范围

适用场景

• 插件开发阶段：开发者本地验证插件结构与语法，快速定位问题
• CI/CD 流程集成：作为自动化检查步骤，在插件提交或 PR 时触发质量校验
• 发布前验证：插件发布到 Buildkite 插件市场前的合规性检查
• 团队协作：统一团队插件开发规范，减少代码评审中的格式类问题

适用范围

• Buildkite 插件开发者（单个插件或多插件项目）
• 基于 Buildkite 的 CI/CD 平台维护团队
• 需要自动化保障插件质量的开发团队

使用方法与配置说明

基本使用（Docker Run）

通过 docker run 命令直接运行，需挂载插件代码目录到容器内，并指定检查路径：

bash
docker run --rm -v $(pwd):/plugin buildkite-plugins/buildkite-plugin-linter \
  --plugin-dir /plugin \
  --format text

参数说明：

• -v $(pwd):/plugin：挂载本地插件代码目录到容器内 /plugin 路径（需替换 $(pwd) 为实际插件目录）
• --plugin-dir /plugin：指定容器内插件代码路径（与挂载路径对应）
• --format text：设置输出格式为文本（默认值）

Docker Compose 配置

创建 docker-compose.yml 简化本地检查流程：

yaml
version: '3.8'
services:
  linter:
    image: buildkite-plugins/buildkite-plugin-linter
    volumes:
      - ./:/plugin  # 挂载本地插件目录到容器内 /plugin
    command: ["--plugin-dir", "/plugin", "--format", "json"]
    environment:
      - BUILDKITE_STRICT_MODE=true  # 启用严格模式（不符合规则时返回非零 exit code）

运行检查：

bash
docker-compose run --rm linter

配置参数详解

命令行参数

环境变量

示例

示例 1：本地检查插件

检查当前目录下的插件代码，输出文本格式结果：

bash
docker run --rm -v $(pwd):/plugin buildkite-plugins/buildkite-plugin-linter \
  --plugin-dir /plugin \
  --format text

输出示例（文本格式）：

[INFO] 检查插件目录: /plugin
[PASS] plugin.yml 语法验证通过
[WARN] 插件描述缺失（建议添加 `description` 字段）
[PASS] 版本兼容性验证通过
[ERROR] hooks/post-command.sh 存在未引用的环境变量 $SECRET_TOKEN（建议使用 `plugin.config` 传递）

示例 2：CI/CD 集成（GitHub Actions）

在 GitHub Actions 中集成，作为 PR 检查步骤：

yaml
# .github/workflows/lint-plugin.yml
name: Lint Buildkite Plugin
on: [pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run Buildkite Plugin Linter
        run: |
          docker run --rm -v $(pwd):/plugin buildkite-plugins/buildkite-plugin-linter \
            --plugin-dir /plugin \
            --strict \
            --format json

注意事项

• 插件目录需包含标准 Buildkite 插件结构（如 plugin.yml、hooks/ 等），否则可能导致检查失败
• 完整规则列表及最新配置说明请参考 GitHub 仓库
• 部分高级规则（如自定义校验逻辑）可能需要通过配置文件（.plugin-linter.yml）扩展，具体格式见***文档