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:

• Run Quick Start command 2 (--syntax-only ).

• If syntax fails, stop and fix errors before continuing.

• Run Quick Start command 3 (--best-practices ) and apply relevant improvements.

• Run Quick Start command 4 (--security-only ) and fix all critical /high findings before merge.

• Optionally run Quick Start command 5 (--test-only ) for local execution checks.

• 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.