gitlab-ci-validator

GitLab CI/CD 验证器

用于验证、检查、测试和保护 .gitlab-ci.yml 配置的综合工具包。

触发短语

当请求包含以下意图时，使用此技能：

• “验证此 .gitlab-ci.yml”
• “为什么这个 GitLab 流水线失败了？”
• “为我们的 GitLab CI 执行安全审查”
• “检查流水线最佳实践”
• “合并前检查 GitLab CI 配置”

设置和先决条件（先运行）

以下所有命令均假定当前工作目录为仓库根目录。

# Ensure validator scripts are executable
chmod +x devops-skills-plugin/skills/gitlab-ci-validator/scripts/*.sh \
  devops-skills-plugin/skills/gitlab-ci-validator/scripts/*.py

# Required runtime
python3 --version

使用唯一的规范命令路径进行编排：

VALIDATOR="bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh"

可选的本地执行工具（用于 --test-only）：

bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/install_tools.sh

快速入门命令

# 1) Full validation (syntax + best practices + security)
$VALIDATOR .gitlab-ci.yml

# 2) Syntax and schema only (required first gate)
$VALIDATOR .gitlab-ci.yml --syntax-only

# 3) Best-practices only (recommended)
$VALIDATOR .gitlab-ci.yml --best-practices

# 4) Security only (required before merge)
$VALIDATOR .gitlab-ci.yml --security-only

# 5) Optional local pipeline structure test (needs gitlab-ci-local + Docker)
$VALIDATOR .gitlab-ci.yml --test-only

# 6) Strict mode (treat best-practice warnings as failure)
$VALIDATOR .gitlab-ci.yml --strict

确定性验证工作流

按顺序执行以下关卡：

1. 运行快速入门命令 2（--syntax-only）。
2. 如果语法检查失败，请停止并修复错误后再继续。
3. 运行快速入门命令 3（--best-practices），并应用相关改进。
4. 运行快速入门命令 4（--security-only），并在合并前修复所有 critical/high 级别的问题。
5. 可选：运行快速入门命令 5（--test-only），检查本地执行情况。
6. 运行快速入门命令 6（--strict），作为最终合并关卡。

必需关卡：语法 + 安全。 推荐关卡：最佳实践。 可选关卡：本地执行测试。

规则严重性说明及文档链接

严重性模型

• critical：直接暴露凭据/机密，或存在高度可信的攻击路径。阻止合并。
• high：可被利用的不安全行为，或严重的安全回退。合并前修复。
• medium：存在具有现实风险的安全加固缺口。跟踪并尽快修复。
• low/suggestion：优化或可维护性改进。

规则类别及其重要性

• 语法规则（yaml-syntax、job-stage-undefined、dependencies-undefined-job）：防止流水线解析失败和依赖项故障。
• 最佳实践规则（cache-missing、artifact-no-expiration、dag-optimization）：降低运行成本并提高流水线吞吐量。
• 安全规则（hardcoded-password、curl-pipe-bash、include-remote-unverified）：降低凭据泄露和供应链风险。

参考资料

• 本地语法参考：devops-skills-plugin/skills/gitlab-ci-validator/docs/gitlab-ci-reference.md
• 本地最佳实践：devops-skills-plugin/skills/gitlab-ci-validator/docs/best-practices.md
• 本地常见问题：devops-skills-plugin/skills/gitlab-ci-validator/docs/common-issues.md
• GitLab CI YAML 参考：https://docs.gitlab.com/ee/ci/yaml/
• GitLab CI/CD 组件：https://docs.gitlab.com/ee/ci/components/
• GitLab 流水线安全指南：https://docs.gitlab.com/ee/ci/pipelines/settings.html

工具或环境受限时的备用方案

• 缺少 python3：
  • 行为：验证器无法运行。
  • 备用方案：安装 Python 3 后重新运行。
• 缺少 PyYAML：
  • 行为：python_wrapper.sh 会在可行时自动创建 .venv 并安装 pyyaml。
  • 受限/离线环境下的备用方案：从内部镜像预先安装 pyyaml，然后重新运行。
• 缺少 gitlab-ci-local、node 或 docker：
  • 行为：--test-only 会报告警告/失败。
  • 备用方案：跳过本地执行测试，继续进行语法、最佳实践和安全关卡。
• 脚本没有执行权限：
  • 行为：出现 Shell 权限错误。
  • 备用方案：重新运行设置部分中的 chmod 命令。

示例

示例 1：验证新流水线

$VALIDATOR examples/basic-pipeline.gitlab-ci.yml --syntax-only
$VALIDATOR examples/basic-pipeline.gitlab-ci.yml --security-only

示例 2：合并前硬性关卡

$VALIDATOR .gitlab-ci.yml --strict

示例 3：CI 集成

stages:
  - validate

validate_gitlab_ci:
  stage: validate
  script:
    - chmod +x devops-skills-plugin/skills/gitlab-ci-validator/scripts/*.sh devops-skills-plugin/skills/gitlab-ci-validator/scripts/*.py
    - bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh .gitlab-ci.yml --strict

单项验证器（高级）

# Syntax validator (via wrapper for PyYAML fallback)
bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/python_wrapper.sh \
  devops-skills-plugin/skills/gitlab-ci-validator/scripts/validate_syntax.py .gitlab-ci.yml

# Best-practices validator
bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/python_wrapper.sh \
  devops-skills-plugin/skills/gitlab-ci-validator/scripts/check_best_practices.py .gitlab-ci.yml

# Security validator
bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/python_wrapper.sh \
  devops-skills-plugin/skills/gitlab-ci-validator/scripts/check_security.py .gitlab-ci.yml

完成标准

• Frontmatter 中的 name 和 description 保持不变。
• 始终使用同一个规范的编排路径。
• 在工作流／使用示例之前列出设置和 chmod 前置条件。
• 快速入门和工作流内容不重复（工作流引用快速入门中的检查关卡）。
• 明确说明严重性判断依据以及规则与文档的对应关系。
• 说明缺少工具和环境受限时的回退行为。
• 示例可从仓库根目录执行。

说明

• 此技能用于验证配置和静态模式，不会执行生产流水线。
• 使用 gitlab-ci-local 或 GitLab CI Lint 确认运行时行为。