gitlab-ci-validator

name	gitlab-ci-validator
description	Comprehensive toolkit for validating, linting, testing, and securing GitLab CI/CD pipeline configurations. Use this skill when working with GitLab CI/CD pipelines, validating pipeline syntax, debugging configuration issues, or implementing best practices.

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.