megabytelabs/yamllint

CodeClimate和独立YAMLLint检查器

由Megabyte Labs维护的性能优化CodeClimate引擎

概述

本仓库包含一个Dockerfile项目，用于生成适用于GitLab CI的CodeClimate引擎（用于YAML检查）和一个紧凑的精简容器（适用于独立YAMLLint检查）。https://github.com/adrienverge/yamllint%E6%98%AFYAML%E6%96%87%E4%BB%B6%E6%A3%80%E6%9F%A5%E7%9A%84%E8%A1%8C%E4%B8%9A%E6%A0%87%E5%87%86%E5%B7%A5%E5%85%B7%EF%BC%8C%E9%87%87%E7%94%A8Python%E7%BC%96%E5%86%99%EF%BC%8C%E5%8F%AF%E6%A3%80%E6%9F%A5%E8%AF%AD%E6%B3%95%E6%9C%89%E6%95%88%E6%80%A7%E3%80%81%E9%94%AE%E9%87%8D%E5%A4%8D%E4%BB%A5%E5%8F%8A%E6%A0%BC%E5%BC%8F%E9%97%AE%E9%A2%98%EF%BC%88%E5%A6%82%E8%A1%8C%E9%95%BF%E5%BA%A6%E3%80%81%E5%B0%BE%E9%9A%8F%E7%A9%BA%E6%A0%BC%E5%92%8C%E7%BC%A9%E8%BF%9B%EF%BC%89%E3%80%82

该项目主要用于将YAMLLint结果集成到GitLab Web界面（GitLab接受与CodeClimate格式非常相似的结果），同时也提供一个轻量级Docker容器，可在任何CI环境中快速运行YAMLLint。

独立使用

如果不需要CodeClimate集成，可使用不带CodeClimate相关代码的latest、slim和版本化镜像，只需从镜像名称中移除codeclimate-字符串。例如，megabytelabs/codeclimate-yamllint对应的独立镜像为megabytelabs/yamllint。完整镜像列表可查看https://hub.docker.com/r/megabytelabs/yamllint%E3%80%82

注意：CodeClimate引擎版本的DockerHub页面除上述链接外，还可通过https://hub.docker.com/r/megabytelabs/codeclimate-yamllint%E8%AE%BF%E9%97%AE%EF%BC%88%E5%89%8D%E7%BC%80%E4%B8%BA%60codeclimate-%60%EF%BC%89%E3%80%82

精简构建

所有CodeClimate引擎项目均包含两个变体：常规构建（使用项目根目录的Dockerfile构建）和slim构建（通过DockerSlim构建）。若追求稳定性并希望使用slim构建，建议引用镜像时指定确切版本（例如megabytelabs/codeclimate-package:5.4.0-slim而非megabytelabs/codeclimate-package:slim）。

版本控制

尽可能将Docker镜像版本与对应软件版本关联。例如，megabytelabs/codeclimate-eslint:5.4.0通常包含5.4.0版本的ESLint（可能存在例外，但这是主要目标）。

测试

通过多种测试方法确保latest和slim构建正常工作：根目录的Dockerfile-test.yml文件（https://github.com/GoogleContainerTools/container-structure-test%EF%BC%89%E7%94%A8%E4%BA%8E%E9%AA%8C%E8%AF%81%E5%AE%B9%E5%99%A8%E5%8A%9F%E8%83%BD%EF%BC%9B%E5%90%8C%E6%97%B6%E5%9C%A8%60test/compare/%60%E7%9B%AE%E5%BD%95%E7%9A%84%E6%A0%B7%E6%9C%AC%E9%A1%B9%E7%9B%AE%E4%B8%8A%E8%BF%90%E8%A1%8C%E5%91%BD%E4%BB%A4%EF%BC%8C%E7%A1%AE%E4%BF%9D%60latest%60%E5%92%8C%60slim%60%E9%95%9C%E5%83%8F%E7%9A%84%E8%BE%93%E5%87%BA%E4%B8%80%E8%87%B4%EF%BC%9B%E9%83%A8%E5%88%86%E5%9C%BA%E6%99%AF%E4%B8%8B%E8%BF%98%E4%B8%BACodeClimate%E5%BC%95%E6%93%8E%E7%9A%84%E8%87%AA%E5%AE%9A%E4%B9%89%E4%BB%A3%E7%A0%81%E5%8C%85%E5%90%AB%E5%8D%95%E5%85%83%E6%B5%8B%E8%AF%95%E3%80%82

要求

• Docker

开发要求

• https://github.com/docker-slim/docker-slim - 用于生成紧凑、安全的镜像
• https://stedolan.github.io/jq/ - 用于JSON交互
• Node.js (>=14.18) - 用于添加开发功能（如预提交钩子和维护任务）
• 更多通过Taskfile.yml动态安装的要求（通过自定义https://github.com/go-task/task%E5%88%86%E6%94%AF**https://github.com/ProfessorManhattan/Bodega**%EF%BC%89

若使用项目提供的开发工具，需运行bash start.sh（或npm i，后者完成后会调用bash start.sh）。start.sh脚本会自动安装构建系统中缺失的依赖（无需sudo）到用户的~/.local/bin目录，并通过Taskfile.yml中定义的任务生成文档。更多详情参见CONTRIBUTING.md。

准备开发时，运行task --menu打开交互式对话框，了解可用的构建命令。

示例

本地测试

可通过以下命令在本地测试工具：

shell
docker run -it -v ${PWD}:/work -w /work --rm megabytelabs/yamllint:latest --help

此命令在容器中运行YAMLLint，完成后自动移除镜像，既确保安全性（应用在容器内运行）又保持文件系统清洁。

添加Bash别名

将以下代码添加到~/.profile（或等效文件），可在任何时候运行YAMLLint命令：

shell
yamllint() {
  docker run -it -v ${PWD}:/work -w /work --rm megabytelabs/yamllint:latest "$@"
}

注意：部分CLI工具无参数时默认运行（如ansible-lint）。本项目Docker镜像默认命令为显示版本，因此需运行ansible-lint .以执行检查。

集成到GitLab CI

项目主要用途是构建可用于CI流水线和GitLab CI CodeClimate分析的Docker容器。

CodeClimate GitLab CI示例

若需改进合并请求的GitLab Web界面，可参考CodeClimate的GitLab CI配置。该配置需在单个CI阶段运行所有检查器，因为GitLab CI仅接受一个CodeClimate报告工件。

CodeClimate CLI步骤

要将CodeClimate集成到项目中，需确保根目录存在正确配置的.codeclimate.yml，最低配置示例如下：

yaml
---
engines:
  yamllint:
    enabled: true
exclude_paths:
  - 'node_modules/**'

运行CodeClimate CLI前，需拉取本项目的CodeClimate镜像并为CodeClimate正确标记：

shell
docker pull megabytelabs/codeclimate-yamllint:latest
docker tag megabytelabs/codeclimate-yamllint:latest codeclimate/codeclimate-yamllint:latest

然后通过--dev参数调用CodeClimate CLI（这是使用非官方codeclimate命名空间DockerHub引擎的唯一方式）：

shell
brew install codeclimate/formulae/codeclimate
codeclimate analyze --dev

生成HTML报告：

shell
brew install codeclimate/formulae/codeclimate
codeclimate analyze --dev -f html > codeclimate-report.html

独立集成

若需在GitLab CI中集成工具而无需CodeClimate，需在GitLab仓库根目录创建.gitlab-ci.yml：

yaml
---
stages:
  - lint

include:
  - remote: https://gitlab.com/megabyte-labs/gitlab-ci/-/raw/master/lint/yamllint.gitlab-ci.yml

配置完成后，每次提交代码时YAMLLint将自动运行（符合上述remote文件中的参数）。生产环境中，建议将remote链接的源代码复制到其他位置并更新链接，避免依赖外部文件变更。

YAMLLint更多信息

https://github.com/adrienverge/yamllint%E6%98%AF%E4%B8%80%E6%AC%BEYAML%E6%96%87%E4%BB%B6%E6%A3%80%E6%9F%A5CLI%E5%B7%A5%E5%85%B7%EF%BC%8C%E5%B9%BF%E5%8F%97%E7%A4%BE%E5%8C%BA%E8%AE%A4%E5%8F%AF%EF%BC%8C%E5%8F%AF%E6%8A%A5%E5%91%8A%E5%90%84%E7%B1%BB%E9%97%AE%E9%A2%98%EF%BC%8C%E5%B8%AE%E5%8A%A9%E5%87%8F%E5%B0%91%E9%94%99%E8%AF%AF%E5%B9%B6%E6%8F%90%E9%AB%98YAML%E6%96%87%E4%BB%B6%E5%8F%AF%E8%AF%BB%E6%80%A7%E3%80%82

与ESLint配合使用

YAMLLint无法自动修复/排序*.yml文件，而ESLint（基于JavaScript）可自动修复部分YAMLLint报告的问题，并按需求排序YAML文件（需较多配置）。推荐参考ESLint共享配置https://github.com/ProfessorManhattan/eslint-config-strict-mode%E5%92%8CGitLab%E5%8F%8B%E5%A5%BD%E7%9A%84CodeClimate%E5%BC%95%E6%93%8Ehttps://github.com/ProfessorManhattan/codeclimate-eslint%E3%80%82

构建Docker容器

若需修改Docker镜像，可按以下步骤上传自定义容器到https://hub.docker.com/%EF%BC%9A

shell
export DOCKERHUB_USERNAME=你的DockerHub用户名
export DOCKERHUB_PASSWORD=你的DockerHub密码
docker login -u "$DOCKERHUB_USERNAME" -p "$DOCKERHUB_PASSWORD" docker.io
docker build --pull -t "$DOCKERHUB_USERNAME/yamllint:latest" .
docker push "$DOCKERHUB_USERNAME/yamllint:latest"

上述命令在设置用户名和密码后，将构建并上传镜像至Docker Hub（公开访问）。此逻辑在GitLab CI任务中实现，与根目录的.gitlab-ci.yml配合使用。

构建精简容器

部分仓库支持通过https://github.com/docker-slim/docker-slim%E5%88%9B%E5%BB%BA%E7%B2%BE%E7%AE%80%E6%9E%84%E5%BB%BA%E3%80%82%E6%A0%B9%E6%8D%AEDockerSlim%E6%96%87%E6%A1%A3%EF%BC%8C%E7%B2%BE%E7%AE%80%E5%AE%B9%E5%99%A8%E5%8F%AF%E5%87%8F%E5%B0%8F%E9%95%9C%E5%83%8F%E5%A4%A7%E5%B0%8F%E5%B9%B6%E9%80%9A%E8%BF%87%E5%87%8F%E5%B0%91***%E9%9D%A2%E6%8F%90%E9%AB%98%E5%AE%89%E5%85%A8%E6%80%A7%EF%BC%8C%E9%83%A8%E5%88%86%E9%95%9C%E5%83%8F%E5%8F%AF%E7%BC%A9%E5%87%8F%E8%87%B3%E5%8E%9F%E5%A4%A7%E5%B0%8F%E7%9A%841/448.76%EF%BC%88%E5%A6%82700MB%E2%86%921.56MB%EF%BC%89%EF%BC%8C%E5%8E%9F%E7%90%86%E6%98%AF%E7%A7%BB%E9%99%A4%E5%AE%B9%E5%99%A8%E4%B8%AD%E4%B8%8D%E5%BF%85%E8%A6%81%E7%9A%84%E5%86%85%E5%AE%B9%E3%80%82

项目提供package.json中定义的命令，运行npm i（或无Node.js时运行bash start.sh）后，执行task docker:build即可构建latest和slim版本。

手动构建并发布slim镜像到Docker Hub的示例命令：

shell
export DOCKERHUB_USERNAME=你的DockerHub用户名
export DOCKERHUB_PASSWORD=你的DockerHub密码
docker login -u "$DOCKERHUB_USERNAME" -p "$DOCKERHUB_PASSWORD" docker.io
docker build -t "$DOCKERHUB_USERNAME/yamllint:latest" .
docker-slim build --tag $DOCKERHUB_USERNAME/yamllint:slim $DOCKERHUB_USERNAME/yamllint:latest
docker push "$DOCKERHUB_USERNAME/yamllint:slim"

可修改package.json中blueprint.dockerSlimCommand的DockerSlim命令以优化构建。若有改进，欢迎https://github.com/megabyte-labs/codeclimate-yamllint/issues/new%E3%80%82

构建工具

项目包含多个开发配置文件，旨在简化团队开发。若安装了最新版Node.js，可通过在根目录运行npm i（或无Node.js时运行bash start.sh）启动构建工具，然后运行task --list查看可用开发功能，或task --menu打开交互式开发菜单。

注意：项目使用自定义版本的https://github.com/go-task/task%EF%BC%8C%E8%8B%A5%E5%B7%B2%E5%AE%89%E8%A3%85%E5%8E%9F%E7%89%88%EF%BC%8C%E9%9C%80%E6%9B%BF%E6%8D%A2%E4%B8%BA%E8%87%AA%E5%AE%9A%E4%B9%89%E7%89%88%E6%9C%AC%E6%88%96%E4%BD%BF%E7%94%A8%E4%B8%8D%E5%90%8C%E7%9A%84%60task%60%E5%91%BD%E4%BB%A4%E5%90%8D%E7%A7%B0%E3%80%82

更多详情参见CONTRIBUTING.md。

理念

持续集成（CI）工具可显著提高开发效率，支持代码错误扫描和自动部署等功能。本仓库的Docker容器是CI拼图的一部分，几乎所有CI流水线Docker项目均专注于单一用途。

通过内部构建容器，可精确控制代码内容，并确保CI镜像尽可能小，以便快速下载和运行。基于本仓库，你也可轻松创建内部CI流水线容器镜像。

项目中的隐藏文件（前缀为.）多为开发配置，旨在简化开发、提高效率，并通过严格标准确保团队开发的一致性。

贡献

欢迎贡献、报告问题和提出功能请求！可查看https://github.com/megabyte-labs/codeclimate-yamllint/issues%E3%80%82%E8%B4%A1%E7%8C%AE%E5%89%8D%E8%AF%B7%E5%8F%82%E8%80%83https://github.com/megabyte-labs/codeclimate-yamllint/blob/master/docs/CONTRIBUTING.md%E3%80%82

许可证

本项目采用MIT许可证。详情参见https://github.com/megabyte-labs/codeclimate-yamllint/blob/master/LICENSE%E6%96%87%E4%BB%B6%E3%80%82