Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
akin-ozer avatar

Gitlab Ci Validator

  • 416 installs
  • 286 repo stars
  • Updated July 26, 2026
  • akin-ozer/cc-devops-skills

gitlab-ci-validator is a Claude Code skill that validates GitLab CI YAML for schema, job graph, best practices, and security for developers who need to stop broken pipelines before they waste runner time.

About

gitlab-ci-validator is a DevOps skill in akin-ozer/cc-devops-skills that orchestrates a 6-gate validation workflow on .gitlab-ci.yml through validate_gitlab_ci.sh. Required gates cover syntax and security; recommended gates add best practices; optional --test-only runs gitlab-ci-local when Docker is available. Three Python validators check syntax, best practices, and security with severity levels from critical through suggestion. Developers reach for gitlab-ci-validator when editing stages, includes, or job dependencies and need pre-merge CI review on GitLab.

  • Validate GitLab CI YAML before push
  • Detect job dependency and syntax issues
  • Prevent broken pipelines from blocking releases
  • Save runner minutes on bad configs
  • Improve CI maintainability across repos

Gitlab Ci Validator by the numbers

  • 416 all-time installs (skills.sh)
  • Ranked #286 of 1,435 DevOps & CI/CD skills by installs in the Skillselion catalog
  • Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/akin-ozer/cc-devops-skills --skill gitlab-ci-validator

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs416
repo stars286
Last updatedJuly 26, 2026
Repositoryakin-ozer/cc-devops-skills

How do you validate GitLab CI YAML before pipeline runs?

Validate GitLab CI YAML for schema, job graph, and common misconfigurations before pipeline runs waste runner time or block releases.

Who is it for?

Developers editing GitLab CI configs who want a structured 6-gate validation workflow before merge.

Skip if: Repositories on GitHub Actions or Azure Pipelines without a .gitlab-ci.yml file.

When should I use this skill?

A developer changes .gitlab-ci.yml or asks to validate, lint, or security-review a GitLab pipeline.

What you get

Reviewed .gitlab-ci.yml with syntax, security, and best-practice findings ranked by critical through suggestion severity.

  • Pipeline YAML issue report
  • Severity-ranked security and best-practice findings

By the numbers

  • 6-gate deterministic validation workflow from syntax through strict mode
  • 3 dedicated Python validators: validate_syntax.py, check_best_practices.py, check_security.py

Files

SKILL.mdMarkdownGitHub ↗

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-start and workflow are non-duplicative (workflow references quick-start gates).
  • Severity rationale and rule-to-doc references are explicit.
  • Fallback behavior is documented for missing tools and constrained environments.
  • Examples are executable from repository root.

Notes

  • This skill validates configuration and static patterns; it does not execute production pipelines.
  • Use gitlab-ci-local or GitLab CI Lint for runtime behavior confirmation.

Related skills

How it compares

Pick gitlab-ci-validator when validating GitLab CI job graphs and include rules, not a language-agnostic YAML formatter.

FAQ

What gates does gitlab-ci-validator enforce?

gitlab-ci-validator enforces a 6-gate workflow on .gitlab-ci.yml: syntax-only first, then best-practices, security-only, optional --test-only with gitlab-ci-local, and a final --strict merge gate. Syntax and security are required before merge.

Does gitlab-ci-validator run pipelines?

gitlab-ci-validator performs static configuration review and does not execute production pipelines. Optional --test-only can run gitlab-ci-local when Docker and Node are installed, but the primary value is pre-merge YAML validation.

DevOps & CI/CDdevopstestinggit

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.