git:20260316.2d4c8cf to git:20261001.6ed2a6a

---

name: gitlab-ci-validator

description: Validates .gitlab-ci.yml syntax, detects security misconfigurations in job definitions, checks for deprecated keywords, ensures proper stage ordering, and audits pipeline configurations for best practices. Use when working with .gitlab-ci.yml files, validating GitLab CI/CD pipeline syntax, debugging configuration errors, checking for hardcoded secrets or credentials in pipeline jobs, optimizing pipeline performance with DAG or cache, or performing security audits on GitLab CI/CD configurations.

---

# GitLab CI/CD Validator

Validates, lints, tests, and secures GitLab CI/CD pipeline configurations (`.gitlab-ci.yml` files) across three layers: syntax/schema validation, best practices analysis, and security scanning.

## Core Validation Workflow

### 1. Syntax Validation (Required first)

```bash

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

```

Checks: YAML structure, GitLab CI schema compliance, job definitions, stage references, dependency graphs (`needs`/`dependencies`/`extends`), include configurations (component, project, remote, local, template), circular dependency detection, and 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 (Recommended)

```bash

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

```

Checks: Cache usage for dependency installation, artifact expiration settings, DAG optimization with `needs`, parallel execution opportunities, Docker image version pinning, deprecated `only`/`except` → `rules` migration, missing timeouts and retries, resource group usage.

**Action:** Review suggestions and apply relevant optimizations.

### 3. Security Audit (Required)

```bash

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

```

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 (`chmod 777`), overly broad artifact paths, variable masking, path traversal in local includes.

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

### 4. Local Pipeline Testing (Optional)

```bash

# 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

```

Simulates local pipeline execution to test job ordering, dependencies, and environment setup. Requires Docker and `gitlab-ci-local`.

### 5. Complete Validation

```bash

# Full validation (all three layers)

bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml

# Strict mode (fail on warnings)

bash scripts/validate_gitlab_ci.sh .gitlab-ci.yml --strict

```

## Usage

### Validation Options

```bash

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

```

### Individual Validators

```bash

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

```

## Output Example

```

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

Validation Summary

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

Syntax Validation: PASSED

Best Practices: WARNINGS

Security Scan: PASSED

✓ All validation checks passed

```

## CI/CD Integration

```yaml

stages:

- validate

validate_pipeline:

stage: validate

script:

- pip3 install PyYAML

```

## Adding Custom Validation Rules

Add custom rules directly to the relevant script:

```python

# 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

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"

))

```

- Syntax rules: `scripts/validate_syntax.py`

- Best practice rules: `scripts/check_best_practices.py`

- Security rules: `scripts/check_security.py`

## Requirements

- **Python 3.7+**

- **PyYAML**: `pip3 install PyYAML`

- **Bash**: For the orchestrator script

## Anti-Patterns

### NEVER skip syntax validation before running `gitlab-ci-local`

### NEVER ignore `only`/`except` deprecation warnings

### NEVER validate the pipeline file without also checking all referenced `include:` targets

### NEVER run `--strict` as the first validation step on an unfamiliar pipeline

## References

```bash

# Test with examples

```

## Fetching Latest Documentation

When encountering custom GitLab features or version-specific requirements, this 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 pages from docs.gitlab.com

---

**Note:** 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.