GitLab CI/CD Validator 综合工具包，用于验证、检查、测试和保护GitLab CI/CD流水线配置（.gitlab-ci.yml文件）。当您使用GitLab CI/CD流水线、验证流水线语法、调试配置问题、实施最佳实践或执行安全审计时，请使用这个技能。
何时使用这个技能
在以下场景中使用gitlab-ci-validator技能：
- ✅ 处理
.gitlab-ci.yml文件 - ✅ 验证GitLab CI/CD流水线语法和结构
- ✅ 调试流水线配置错误
- ✅ 实施GitLab CI/CD最佳实践
- ✅ 对流水线配置执行安全审计
- ✅ 检查硬编码的秘密或凭证
- ✅ 优化流水线性能（缓存、DAG、并行执行）
- ✅ 确保符合安全标准
- ✅ GitLab CI/CD配置的代码审查
- ✅ 迁移或重构流水线配置
特性
1. 语法验证
- ✅ YAML语法检查
- ✅ GitLab CI模式验证
- ✅ 必填字段验证
- ✅ 作业命名约定
- ✅ 阶段引用验证
- ✅ 依赖验证（needs, dependencies, extends）
- ✅ 规则和条件逻辑验证
- ✅ 工件和缓存配置验证
2. 最佳实践检查
- ✅ 缓存使用依赖安装
- ✅ 工件到期设置
- ✅ 正确使用’needs’与’dependencies’
- ✅ 使用’rules’与过时的’only’/‘except’
- ✅ 可中断作业配置
- ✅ 重试配置
- ✅ 超时设置
- ✅ Docker镜像版本固定
- ✅ DAG（有向无环图）优化机会
- ✅ 并行执行机会
- ✅ 资源优化（resource_group）
- ✅ 环境配置
- ✅ 使用’extends’的模板
3. 安全扫描
- ✅ 硬编码秘密和凭证检测
- ✅ 日志中的秘密暴露
- ✅ 不安全的Docker镜像使用（:latest标签）
- ✅ 危险脚本模式（curl | bash, eval, chmod 777）
- ✅ 不安全依赖安装
- ✅ 变量安全（掩蔽、受保护变量）
- ✅ 包含安全（未固定引用）
- ✅ 工件安全（过于广泛的路径）
- ✅ SSL/TLS验证绕过
- ✅ 调试模式警告
- ✅ NEW: 组件包含验证（GitLab 17.0+）
- ✅ NEW: 所有包含类型（组件、项目、远程、本地、模板）
核心验证工作流
按照这个工作流验证GitLab CI/CD流水线，以尽早发现问题并确保配置质量：
1. 初始验证（语法和模式）
从语法验证开始，以捕捉YAML错误、模式违规和结构问题：
# 快速语法检查（最快）
bash scripts/validate_gitlab_ci.sh --syntax-only .gitlab-ci.yml
它检查什么：
- YAML语法和结构
- GitLab CI模式合规性
- 作业定义和必填字段
- 阶段引用和依赖
- 包含配置（组件、项目、远程、本地、模板）
- 组件格式和版本验证
- 循环依赖检测
- GitLab限制（最大500个作业，255字符作业名称，最大50个需求，100个最大组件）
操作： 在继续之前修复所有语法错误。
2. 最佳实践审查
通过语法验证后，检查优化机会和最佳实践：
# 最佳实践分析
bash scripts/validate_gitlab_ci.sh --best-practices .gitlab-ci.yml
它检查什么：
- 依赖安装的缓存使用
- 工件到期设置
- DAG优化与’needs’
- 并行执行机会
- 图像版本固定
- 过时的语法（only/except → rules）
- 资源优化
- 缺少超时和重试
操作： 审查建议并应用相关优化。
3. 安全审计
执行全面的安全扫描以识别漏洞：
# 安全扫描
bash scripts/validate_gitlab_ci.sh --security-only .gitlab-ci.yml
它检查什么：
- 硬编码的秘密和凭证
- 组件安全（版本固定、可信来源）
- 远程包含完整性
- 不安全的脚本模式（curl | bash, eval）
- SSL/TLS验证绕过
- 危险的文件权限
- 工件安全
- 变量掩蔽
- 本地包含路径遍历
操作： 立即修复所有关键和高严重性安全问题。
4. 本地流水线测试（可选）
对于复杂的更改，在推送之前本地测试流水线执行：
# 首先安装gitlab-ci-local（需要Docker和Node.js）
bash scripts/install_tools.sh
# 本地测试流水线
gitlab-ci-local
# 或通过验证器脚本
bash scripts/validate_gitlab_ci.sh --test-only .gitlab-ci.yml
它做什么：
- 本地模拟流水线执行
- 测试作业排序和依赖
- 验证环境设置
- 及早捕捉运行时错误
注意： 需要Docker和gitlab-ci-local安装。
5. 完整验证
一起运行所有验证器以进行全面检查：
# 完整验证流水线
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml
# 严格模式（警告时失败）
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --strict
工作流总结
┌─────────────────────────────────────────────────────────────┐
│ 1. 语法验证（必需） │
│ ├─ YAML结构 │
│ ├─ 模式合规性 │
│ ├─ 包含验证（组件、项目等。） │
│ └─ 组件格式和版本 │
│ ↓ │
│ Fix errors → Proceed │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 2. 最佳实践（推荐） │
│ ├─ 缓存优化 │
│ ├─ DAG机会 │
│ ├─ 图像固定 │
│ └─ 资源优化 │
│ ↓ │
│ Review & apply → Proceed │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 3. 安全审计（必需） │
│ ├─ 硬编码秘密 │
│ ├─ 组件安全 │
│ ├─ 包含完整性 │
│ └─ 危险模式 │
│ ↓ │
│ Fix critical issues → Proceed │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 4. 本地测试（可选） │
│ └─ gitlab-ci-local执行 │
│ ↓ │
│ Test & verify → Push │
└─────────────────────────────────────────────────────────────┘
使用方法
基本验证
要验证GitLab CI/CD配置文件：
bash .claude/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh <file-path>
示例：
bash .claude/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh .gitlab-ci.yml
这将运行所有三个验证层：
- 语法验证
- 最佳实践检查
- 安全扫描
验证选项
# 仅运行语法验证
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --syntax-only
# 仅运行最佳实践检查
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --best-practices
# 仅运行安全扫描
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --security-only
# 跳过最佳实践检查
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --no-best-practices
# 跳过安全扫描
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --no-security
# 严格模式（警告时失败）
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --strict
单独验证器
您也可以运行单独的验证脚本：
# 语法验证
python3 scripts/validate_syntax.py .gitlab-ci.yml
# 最佳实践检查
python3 scripts/check_best_practices.py .gitlab-ci.yml
# 安全扫描
python3 scripts/check_security.py .gitlab-ci.yml
输出示例
════════════════════════════════════════════════════════════════════════════════
GitLab CI/CD Validator
════════════════════════════════════════════════════════════════════════════════
文件：.gitlab-ci.yml
[1/3] 运行语法验证...
✓ 语法验证通过
[2/3] 运行最佳实践检查...
SUGGESTIONS (2):
──────────────────────────────────────────────────────────────────────────────
SUGGESTION: Line 15: Job 'build_app' installs dependencies but doesn't use cache [cache-missing]
💡 Suggestion: Add 'cache' configuration to speed up dependency installation
SUGGESTION: Line 42: Job 'deploy_production' should use resource_group [missing-resource-group]
💡 Suggestion: Add 'resource_group' to prevent concurrent deployments
⚠ Best practices check found issues
[3/3] 运行安全扫描...
MEDIUM SEVERITY (1):
──────────────────────────────────────────────────────────────────────────────
MEDIUM: Line 8: Using ':latest' tag in job 'test_job' is a security risk [image-latest-tag]
🔒 Remediation: Pin to specific version or SHA digest
✓ Security scan passed
══════════════════════════════════════════════════════════════════════════════════
验证摘要
══════════════════════════════════════════════════════════════════════════════════
语法验证： 通过
最佳实践： 警告
安全扫描： 通过
════════════════════════════════════════════════════════════════════════════════════
✓ 所有验证检查通过
常见验证场景
场景1：验证新流水线
# 验证语法和结构
bash scripts/validate_gitlab_ci.sh new-pipeline.gitlab-ci.yml
场景2：合并前的安全审计
# 仅运行安全扫描，严格模式
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --security-only --strict
场景3：流水线优化
# 检查最佳实践和优化机会
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --best-practices
场景4：CI/CD集成
# 在您的CI/CD流水线中
stages:
- validate
validate_pipeline:
stage: validate
script:
- pip3 install PyYAML
- bash .claude/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh .gitlab-ci.yml --strict
与Claude代码集成
当Claude代码调用这个技能时，它将：
- 自动检测 项目中的
.gitlab-ci.yml文件 - 运行验证 当您要求验证、检查或审查GitLab CI/CD配置时
- 提供可操作的反馈 带有行号和建议
- 获取额外的文档 从Context7或网络资源中获取，当需要自定义GitLab功能时
示例提示：
- “验证我的GitLab CI流水线”
- “检查这个.gitlab-ci.yml的安全问题”
- “审查我的流水线配置的最佳实践”
- “为什么我的GitLab流水线失败了？”
- “优化我的GitLab CI/CD配置”
验证规则
语法规则
yaml-syntax: 有效的YAML格式job-reserved-keyword: 作业名称不能使用保留关键字job-missing-script: 作业必须有脚本、触发器或扩展job-stage-undefined: 引用的阶段必须已定义dependencies-undefined-job: 引用的作业必须存在rules-not-list: 规则必须是列表cache-invalid-policy: 缓存策略必须是pull、push或pull-push
最佳实践规则
cache-missing: 安装依赖的作业应使用缓存artifact-no-expiration: 工件应有到期设置deprecated-only-except: 使用’rules’而不是’only’/‘except’missing-interruptible: 测试作业应可中断missing-retry: 潜在的不稳定作业应有重试image-latest-tag: 将Docker镜像固定到特定版本dag-optimization: 使用’needs’以加快流水线执行parallel-opportunity: 测试可以从并行化中受益
安全规则
hardcoded-password: 检测到硬编码密码hardcoded-api-key: 检测到硬编码API密钥secret-in-logs: 秘密可能在日志中暴露curl-pipe-bash: 危险的curl | bash模式image-latest-tag: 使用:latest是一个安全风险include-remote-unverified: 未经验证的远程包含variable-hardcoded-secret: 敏感变量带有硬编码值artifact-broad-path: 过于广泛的工件路径
要求
- Python 3.7+
- PyYAML: 安装
pip3 install PyYAML - Bash: 用于运行编排脚本
安装依赖项：
pip3 install PyYAML
文档
在docs/目录中包含全面的文档：
gitlab-ci-reference.md: 完整的GitLab CI/CD YAML语法参考best-practices.md: 详细的最佳实践指南common-issues.md: 常见问题和解决方案
示例
在examples/目录中提供示例GitLab CI/CD配置：
basic-pipeline.gitlab-ci.yml: 简单的三阶段流水线docker-build.gitlab-ci.yml: Docker构建和推送工作流multi-stage.gitlab-ci.yml: 带有DAG的多阶段流水线complex-workflow.gitlab-ci.yml: 带有所有功能的高级工作流component-pipeline.gitlab-ci.yml: NEW - 使用CI/CD组件的GitLab 17.0+流水线
测试示例：
bash scripts/validate_gitlab_ci.sh examples/basic-pipeline.gitlab-ci.yml
# 测试组件验证（GitLab 17.0+）
bash scripts/validate_gitlab_ci.sh examples/component-pipeline.gitlab-ci.yml
获取最新文档
遇到自定义GitLab功能、模块或特定版本要求时，该技能可以：
- 使用Context7 MCP 获取版本感知的GitLab文档
- 使用WebSearch 查找最新的GitLab CI/CD文档
- 使用WebFetch 从docs.gitlab.com检索特定文档页面
这确保验证规则与最新的GitLab CI/CD功能保持最新。
扩展技能
添加自定义验证规则
向验证脚本中添加自定义规则：
- 语法规则：编辑
scripts/validate_syntax.py - 最佳实践规则：编辑
scripts/check_best_practices.py - 安全规则：编辑
scripts/check_security.py
自定义规则示例
# In check_best_practices.py
def _check_custom_rule(self):
"""检查自定义组织规则"""
for job_name, job in self.config.items():
if not self._is_job(job_name):
continue
# 您的自定义验证逻辑
if 'tags' not in job:
self.issues.append(BestPracticeIssue(
'warning',
self._get_line(job_name),
f"Job '{job_name}' should specify runner tags",
'custom-missing-tags',
"Add 'tags' to select appropriate runners"
))
故障排除
Python模块未找到
# 安装PyYAML
pip3 install PyYAML
# 或与homebrew Python
python3 -m pip install PyYAML
权限被拒绝
# 使脚本可执行
chmod +x scripts/*.sh scripts/*.py
验证错误
查看文档：
- 审查
docs/gitlab-ci-reference.md以获取语法参考 - 检查
docs/common-issues.md以获取已知问题 - 咨询
docs/best-practices.md以获取推荐模式
版本历史
v1.1.0 (2025-01-27)
- NEW: 完成所有类型（组件、项目、远程、本地、模板）的包含验证
- NEW: CI/CD组件验证（GitLab 17.0+）
- 组件名称格式验证（org/project@version）
- 版本格式验证（@1.0.0, @~latest, 语义版本控制）
- 组件输入结构验证
- 组件限制验证（每个项目最多100个）
- NEW: 增强所有包含类型的安全检查
- 组件安全（版本固定、可信来源、硬编码输入）
- 远程包含完整性和HTTP/HTTPS验证
- 项目包含引用固定和分支检测
- 本地包含路径遍历检测
- 模板弃用警告
- NEW: gitlab-ci-local集成，用于本地流水线测试
- install_tools.sh脚本用于工具安装
- validate_gitlab_ci.sh中的–test-only模式
- NEW: 核心验证工作流文档
- NEW: component-pipeline.gitlab-ci.yml示例
- 增强验证规则：40+验证规则（之前为25）
- 改进错误消息，提供详细的补救步骤
v1.0.0 (2025-01-18)
- 初始发布
- 带有全面的GitLab CI模式检查的语法验证
- 带有15+规则的最佳实践验证
- 带有25+安全检查的安全扫描
- 全面文档
- 示例流水线配置
- 与Context7集成，获取最新的GitLab文档
贡献
要改进这个技能：
- 在适当的脚本中添加新的验证规则
- 用新模式更新文档
- 添加示例配置
- 用真实世界的GitLab CI/CD文件进行测试
许可
这个技能是DevOps技能集合的一部分。
支持
有问题、疑问或贡献：
- 查阅
docs/目录中的文档 - 查看
examples/目录中的示例 - 咨询GitLab CI/CD文档：https://docs.gitlab.com/ci/
记住：这个技能验证GitLab CI/CD配置，但不执行流水线。使用GitLab的CI Lint工具或gitlab-ci-local测试实际的流水线执行。