陌讯skills聚合平台

gitlab-ci-validator

📁 akin-ozer/cc-devops-skills 📅 13 days ago
9
总安装量
4
周安装量
#32399
全站排名
安装命令
npx skills add https://github.com/akin-ozer/cc-devops-skills --skill gitlab-ci-validator

Agent 安装分布

claude-code 4
opencode 3
gemini-cli 3
replit 2
antigravity 2

Skill 文档

GitLab CI/CD Validator

Comprehensive toolkit for validating, linting, testing, and securing GitLab CI/CD pipeline configurations (.gitlab-ci.yml files). Use this skill when working with GitLab CI/CD pipelines, validating pipeline syntax, debugging configuration issues, implementing best practices, or performing security audits.

When to Use This Skill

Use the gitlab-ci-validator skill in the following scenarios:

  • ✅ Working with .gitlab-ci.yml files
  • ✅ Validating GitLab CI/CD pipeline syntax and structure
  • ✅ Debugging pipeline configuration errors
  • ✅ Implementing GitLab CI/CD best practices
  • ✅ Performing security audits on pipeline configurations
  • ✅ Checking for hardcoded secrets or credentials
  • ✅ Optimizing pipeline performance (cache, DAG, parallel execution)
  • ✅ Ensuring compliance with security standards
  • ✅ Code review of GitLab CI/CD configurations
  • ✅ Migrating or refactoring pipeline configurations

Features

1. Syntax Validation

  • ✅ YAML syntax checking
  • ✅ GitLab CI schema validation
  • ✅ Required fields verification
  • ✅ Job naming conventions
  • ✅ Stage reference validation
  • ✅ Dependency validation (needs, dependencies, extends)
  • ✅ Rules and conditional logic validation
  • ✅ Artifact and cache configuration validation

2. Best Practices Checking

  • ✅ Cache usage for dependency installation
  • ✅ Artifact expiration settings
  • ✅ Proper use of ‘needs’ vs ‘dependencies’
  • ✅ Use of ‘rules’ vs deprecated ‘only’/’except’
  • ✅ Interruptible job configuration
  • ✅ Retry configuration
  • ✅ Timeout settings
  • ✅ Docker image version pinning
  • ✅ DAG (Directed Acyclic Graph) optimization opportunities
  • ✅ Parallel execution opportunities
  • ✅ Resource optimization (resource_group)
  • ✅ Environment configuration
  • ✅ Template usage with ‘extends’

3. Security Scanning

  • ✅ Hardcoded secrets and credentials detection
  • ✅ Secrets exposure in logs
  • ✅ Insecure Docker image usage (:latest tags)
  • ✅ Dangerous script patterns (curl | bash, eval, chmod 777)
  • ✅ Insecure dependency installation
  • ✅ Variable security (masked, protected variables)
  • ✅ Include security (unpinned references)
  • ✅ Artifact security (overly broad paths)
  • ✅ SSL/TLS verification bypasses
  • ✅ Debug mode warnings
  • ✅ NEW: Component include validation (GitLab 17.0+)
  • ✅ NEW: All include types (component, project, remote, local, template)

Core Validation Workflow

Follow this workflow when validating GitLab CI/CD pipelines to catch issues early and ensure configuration quality:

1. Initial Validation (Syntax & Schema)

Start with syntax validation to catch YAML errors, schema violations, and structural issues:

# Quick syntax check (fastest)
bash scripts/validate_gitlab_ci.sh --syntax-only .gitlab-ci.yml

What it checks:

  • YAML syntax and structure
  • GitLab CI schema compliance
  • Job definitions and required fields
  • Stage references and dependencies
  • Include configurations (component, project, remote, local, template)
  • Component format and version validation
  • Circular dependency detection
  • GitLab limits (500 jobs max, 255 char job names, 50 max needs, 100 max components)

Action: Fix all syntax errors before proceeding.

2. Best Practices Review

After passing syntax validation, check for optimization opportunities and best practices:

# Best practices analysis
bash scripts/validate_gitlab_ci.sh --best-practices .gitlab-ci.yml

What it checks:

  • Cache usage for dependency installation
  • Artifact expiration settings
  • DAG optimization with ‘needs’
  • Parallel execution opportunities
  • Image version pinning
  • Deprecated syntax (only/except → rules)
  • Resource optimization
  • Missing timeouts and retries

Action: Review suggestions and apply relevant optimizations.

3. Security Audit

Perform a comprehensive security scan to identify vulnerabilities:

# Security scan
bash scripts/validate_gitlab_ci.sh --security-only .gitlab-ci.yml

What it checks:

  • Hardcoded secrets and credentials
  • Component security (version pinning, trusted sources)
  • Remote include integrity
  • Insecure script patterns (curl | bash, eval)
  • SSL/TLS verification bypasses
  • Dangerous file permissions
  • Artifact security
  • Variable masking
  • Path traversal in local includes

Action: Fix all critical and high-severity security issues immediately.

4. Local Pipeline Testing (Optional)

For complex changes, test pipeline execution locally before pushing:

# Install gitlab-ci-local first (requires Docker and Node.js)
bash scripts/install_tools.sh

# Test pipeline locally
gitlab-ci-local

# Or via the validator script
bash scripts/validate_gitlab_ci.sh --test-only .gitlab-ci.yml

What it does:

  • Simulates pipeline execution locally
  • Tests job ordering and dependencies
  • Validates environment setup
  • Catches runtime errors early

Note: Requires Docker and gitlab-ci-local installation.

5. Complete Validation

Run all validators together for comprehensive checking:

# Full validation pipeline
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml

# Strict mode (fail on warnings)
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --strict

Workflow Summary

┌─────────────────────────────────────────────────────────────┐
│ 1. Syntax Validation (Required)                             │
│    ├─ YAML structure                                         │
│    ├─ Schema compliance                                      │
│    ├─ Include validation (component, project, etc.)         │
│    └─ Component format & version                            │
│         ↓                                                    │
│    Fix errors → Proceed                                      │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. Best Practices (Recommended)                             │
│    ├─ Cache optimization                                     │
│    ├─ DAG opportunities                                      │
│    ├─ Image pinning                                          │
│    └─ Resource optimization                                  │
│         ↓                                                    │
│    Review & apply → Proceed                                  │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. Security Audit (Required)                                │
│    ├─ Hardcoded secrets                                     │
│    ├─ Component security                                     │
│    ├─ Include integrity                                      │
│    └─ Dangerous patterns                                     │
│         ↓                                                    │
│    Fix critical issues → Proceed                             │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. Local Testing (Optional)                                 │
│    └─ gitlab-ci-local execution                             │
│         ↓                                                    │
│    Test & verify → Push                                      │
└─────────────────────────────────────────────────────────────┘

Usage

Basic Validation

To validate a GitLab CI/CD configuration file:

bash .claude/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh <file-path>

Example:

bash .claude/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh .gitlab-ci.yml

This runs all three validation layers:

  1. Syntax validation
  2. Best practices check
  3. Security scan

Validation Options

# Run only syntax validation
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --syntax-only

# Run only best practices check
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --best-practices

# Run only security scan
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --security-only

# Skip best practices check
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --no-best-practices

# Skip security scan
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --no-security

# Strict mode (fail on warnings)
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --strict

Individual Validators

You can also run individual validation scripts:

# Syntax validation
python3 scripts/validate_syntax.py .gitlab-ci.yml

# Best practices check
python3 scripts/check_best_practices.py .gitlab-ci.yml

# Security scan
python3 scripts/check_security.py .gitlab-ci.yml

Output Example

════════════════════════════════════════════════════════════════════════════════
  GitLab CI/CD Validator
════════════════════════════════════════════════════════════════════════════════

File: .gitlab-ci.yml

[1/3] Running syntax validation...

✓ Syntax validation passed

[2/3] Running best practices check...

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] Running security scan...

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

════════════════════════════════════════════════════════════════════════════════
  Validation Summary
════════════════════════════════════════════════════════════════════════════════

Syntax Validation:      PASSED
Best Practices:         WARNINGS
Security Scan:          PASSED

════════════════════════════════════════════════════════════════════════════════

✓ All validation checks passed

Common Validation Scenarios

Scenario 1: Validating a New Pipeline

# Validate syntax and structure
bash scripts/validate_gitlab_ci.sh new-pipeline.gitlab-ci.yml

Scenario 2: Security Audit Before Merge

# Run security scan only with strict mode
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --security-only --strict

Scenario 3: Pipeline Optimization

# Check for best practices and optimization opportunities
bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --best-practices

Scenario 4: CI/CD Integration

# In your CI/CD pipeline
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

Integration with Claude Code

When Claude Code invokes this skill, it will:

  1. Automatically detect .gitlab-ci.yml files in the project
  2. Run validation when you ask to validate, check, or review GitLab CI/CD configurations
  3. Provide actionable feedback with line numbers and suggestions
  4. Fetch additional documentation from Context7 or web sources when needed for custom GitLab features

Example prompts:

  • “Validate my GitLab CI pipeline”
  • “Check this .gitlab-ci.yml for security issues”
  • “Review my pipeline configuration for best practices”
  • “Why is my GitLab pipeline failing?”
  • “Optimize my GitLab CI/CD configuration”

Validation Rules

Syntax Rules

  • yaml-syntax: Valid YAML formatting
  • job-reserved-keyword: Job names cannot use reserved keywords
  • job-missing-script: Jobs must have script, trigger, or extends
  • job-stage-undefined: Referenced stages must be defined
  • dependencies-undefined-job: Referenced jobs must exist
  • rules-not-list: Rules must be a list
  • cache-invalid-policy: Cache policy must be pull, push, or pull-push

Best Practice Rules

  • cache-missing: Dependency installation jobs should use cache
  • artifact-no-expiration: Artifacts should have expiration
  • deprecated-only-except: Use ‘rules’ instead of ‘only’/’except’
  • missing-interruptible: Test jobs should be interruptible
  • missing-retry: Potentially flaky jobs should have retry
  • image-latest-tag: Pin Docker images to specific versions
  • dag-optimization: Use ‘needs’ for faster pipeline execution
  • parallel-opportunity: Tests could benefit from parallelization

Security Rules

  • hardcoded-password: Hardcoded passwords detected
  • hardcoded-api-key: Hardcoded API keys detected
  • secret-in-logs: Secrets may be exposed in logs
  • curl-pipe-bash: Dangerous curl | bash pattern
  • image-latest-tag: Using :latest is a security risk
  • include-remote-unverified: Remote includes without verification
  • variable-hardcoded-secret: Sensitive variables with hardcoded values
  • artifact-broad-path: Overly broad artifact paths

Requirements

  • Python 3.7+
  • PyYAML: Install with pip3 install PyYAML
  • Bash: For running the orchestrator script

Install dependencies:

pip3 install PyYAML

Documentation

Comprehensive documentation is included in the docs/ directory:

  • gitlab-ci-reference.md: Complete GitLab CI/CD YAML syntax reference
  • best-practices.md: Detailed best practices guide
  • common-issues.md: Common issues and solutions

Examples

Example GitLab CI/CD configurations are provided in the examples/ directory:

  • basic-pipeline.gitlab-ci.yml: Simple three-stage pipeline
  • docker-build.gitlab-ci.yml: Docker build and push workflow
  • multi-stage.gitlab-ci.yml: Multi-stage pipeline with DAG
  • complex-workflow.gitlab-ci.yml: Advanced workflow with all features
  • component-pipeline.gitlab-ci.yml: NEW – GitLab 17.0+ pipeline using CI/CD components from the Catalog

Test the skill with examples:

bash scripts/validate_gitlab_ci.sh examples/basic-pipeline.gitlab-ci.yml

# Test component validation (GitLab 17.0+)
bash scripts/validate_gitlab_ci.sh examples/component-pipeline.gitlab-ci.yml

Fetching Latest Documentation

When encountering custom GitLab features, modules, or specific version requirements, the skill can:

  1. Use Context7 MCP to fetch version-aware GitLab documentation
  2. Use WebSearch to find latest GitLab CI/CD documentation
  3. Use WebFetch to retrieve specific documentation pages from docs.gitlab.com

This ensures validation rules stay current with the latest GitLab CI/CD features.

Extending the Skill

Adding Custom Validation Rules

Add custom rules to the validation scripts:

  1. Syntax rules: Edit scripts/validate_syntax.py
  2. Best practice rules: Edit scripts/check_best_practices.py
  3. Security rules: Edit scripts/check_security.py

Custom Rule Example

# In check_best_practices.py
def _check_custom_rule(self):
    """Check for custom organization rule"""
    for job_name, job in self.config.items():
        if not self._is_job(job_name):
            continue

        # Your custom validation logic
        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"
            ))

Troubleshooting

Python Module Not Found

# Install PyYAML
pip3 install PyYAML

# Or with homebrew Python
python3 -m pip install PyYAML

Permission Denied

# Make scripts executable
chmod +x scripts/*.sh scripts/*.py

Validation Errors

Check the documentation:

  • Review docs/gitlab-ci-reference.md for syntax reference
  • Check docs/common-issues.md for known issues
  • Consult docs/best-practices.md for recommended patterns

Version History

v1.1.0 (2025-01-27)

  • NEW: Complete include validation for all types (component, project, remote, local, template)
  • NEW: CI/CD Component validation (GitLab 17.0+)
    • Component name format validation (org/project@version)
    • Version format validation (@1.0.0, @~latest, semantic versioning)
    • Component inputs structure validation
    • Component limit validation (max 100 per project)
  • NEW: Enhanced security checks for all include types
    • Component security (version pinning, trusted sources, hardcoded inputs)
    • Remote include integrity and HTTP/HTTPS validation
    • Project include ref pinning and branch detection
    • Local include path traversal detection
    • Template deprecation warnings
  • NEW: gitlab-ci-local integration for local pipeline testing
    • install_tools.sh script for tool installation
    • –test-only mode in validate_gitlab_ci.sh
  • NEW: Core Validation Workflow documentation
  • NEW: component-pipeline.gitlab-ci.yml example
  • Enhanced validation rules: 40+ validation rules (was 25)
  • Improved error messages with detailed remediation steps

v1.0.0 (2025-01-18)

  • Initial release
  • Syntax validation with comprehensive GitLab CI schema checking
  • Best practices validation with 15+ rules
  • Security scanning with 25+ security checks
  • Comprehensive documentation
  • Example pipeline configurations
  • Integration with Context7 for latest GitLab docs

Contributing

To improve this skill:

  1. Add new validation rules to appropriate scripts
  2. Update documentation with new patterns
  3. Add example configurations
  4. Test with real-world GitLab CI/CD files

License

This skill is part of the DevOps Skills collection.

Support

For issues, questions, or contributions:

  • Check documentation in docs/ directory
  • Review examples in examples/ directory
  • Consult GitLab CI/CD documentation: https://docs.gitlab.com/ci/

Remember: This skill validates GitLab CI/CD configurations but does not execute pipelines. Use GitLab’s CI Lint tool or gitlab-ci-local for testing actual pipeline execution.

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台
本页面由 陌讯 Skills 聚合平台 收录整理，数据定期更新。