/gitlab-ci-validator

name: gitlab-ci-validator
description: Validate, lint, audit, or fix .gitlab-ci.yml pipelines, stages, and jobs.

GitLab CI/CD Validator

Comprehensive toolkit for validating, linting, testing, and securing `.gitlab-ci.yml` configurations.

Trigger Phrases

Use this skill when requests include intent like:

• "Validate this `.gitlab-ci.yml`"
• "Why is this GitLab pipeline failing?"
• "Run a security review for our GitLab CI"
• "Check pipeline best practices"
• "Lint GitLab CI config before merge"

Setup And Prerequisites (Run First)

All commands below assume repository root as current working directory.

# 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

Use one canonical command path for orchestration:

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

Optional local execution tooling (for `--test-only`):

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

Quick Start Commands

# 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

Deterministic Validation Workflow

Follow these gates in order:

1. Run Quick Start command `2` (`--syntax-only`). 2. If syntax fails, stop and fix errors before continuing. 3. Run Quick Start command `3` (`--best-practices`) and apply relevant improvements. 4. Run Quick Start command `4` (`--security-only`) and fix all `critical`/`high` findings before merge. 5. Optionally run Quick Start command `5` (`--test-only`) for local execution checks. 6. Run Quick Start command `6` (`--strict`) for final merge gate.

Required gates: syntax + security. Recommended gate: best practices. Optional gate: local execution test.

Rule Severity Rationale And Documentation Links

Severity Model

• `critical`: Direct credential/secret exposure or high-confidence compromise path. Block merge.
• `high`: Exploitable unsafe behavior or strong security regression. Fix before merge.
• `medium`: Security hardening gap with realistic risk. Track and fix soon.
• `low`/`suggestion`: Optimization or maintainability improvement.

Rule Classes And Why They Matter

• Syntax rules (`yaml-syntax`, `job-stage-undefined`, `dependencies-undefined-job`): prevent pipeline parse and dependency failures.
• Best-practice rules (`cache-missing`, `artifact-no-expiration`, `dag-optimization`): reduce runtime cost and improve pipeline throughput.
• Security rules (`hardcoded-password`, `curl-pipe-bash`, `include-remote-unverified`): reduce credential leaks and supply-chain risk.

References

• Local syntax reference: `devops-skills-plugin/skills/gitlab-ci-validator/docs/gitlab-ci-reference.md`
• Local best practices: `devops-skills-plugin/skills/gitlab-ci-validator/docs/best-practices.md`
• Local common issues: `devops-skills-plugin/skills/gitlab-ci-validator/docs/common-issues.md`
• GitLab CI YAML reference: https://docs.gitlab.com/ee/ci/yaml/
• GitLab CI/CD components: https://docs.gitlab.com/ee/ci/components/
• GitLab pipeline security guidance: https://docs.gitlab.com/ee/ci/pipelines/settings.html

Fallbacks For Tool Or Environment Constraints

• Missing `python3`:
• Behavior: validator cannot run.
• Fallback: install Python 3 and rerun.
• Missing `PyYAML`:
• Behavior: `python_wrapper.sh` auto-creates `.venv` and installs `pyyaml` when possible.
• Fallback in restricted/offline environments: pre-install `pyyaml` from an internal mirror, then rerun.
• Missing `gitlab-ci-local`, `node`, or `docker`:
• Behavior: `--test-only` reports warning/failure.
• Fallback: skip local execution testing and continue with syntax/best-practice/security gates.
• No execute permission on scripts:
• Behavior: shell permission errors.
• Fallback: rerun the setup `chmod` command from the Setup section.

Examples

Example 1: New Pipeline Validation

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

Example 2: Pre-Merge Hard Gate

$VALIDATOR .gitlab-ci.yml --strict

Example 3: CI Integration

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

Individual Validators (Advanced)

# 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

Done Criteria

• Frontmatter `name` and `description` unchanged.
• One canonical orchestrator path is used consistently.
• Setup and `chmod` prerequisites appear before workflow/use examples.
• Quick