gitlab-ci-validator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitLab CI/CD Validator

GitLab CI/CD 验证工具

Comprehensive toolkit for validating, linting, testing, and securing

.gitlab-ci.yml

configurations.

一款用于验证、检查、测试和加固

.gitlab-ci.yml

配置的综合工具集。

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"

当需求包含以下意图时，可使用本技能：

"验证这份
```
.gitlab-ci.yml
```
"
"为什么这个GitLab流水线运行失败？"
"为我们的GitLab CI执行安全审计"
"检查流水线最佳实践"
"合并前检查GitLab CI配置"

Setup And Prerequisites (Run First)

安装与前提条件（先执行）

All commands below assume repository root as current working directory.

bash

undefined

以下所有命令均假设当前工作目录为仓库根目录。

bash

undefined

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:

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

Optional local execution tooling (for

--test-only

bash

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

python3 --version


使用统一的命令路径来调用工具：

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

可选的本地执行工具（用于

--test-only

参数）：

bash

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

Quick Start Commands

快速开始命令

bash

undefined

bash

undefined

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

undefined

$VALIDATOR .gitlab-ci.yml --strict

undefined

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.

按顺序执行以下检查步骤：

执行快速开始命令
```
2
```
（
```
--syntax-only
```
）。
如果语法检查失败，请停止并修复错误后再继续。
执行快速开始命令
```
3
```
（
```
--best-practices
```
）并应用相关优化建议。
执行快速开始命令
```
4
```
（
```
--security-only
```
），在合并前修复所有
```
critical
```
（严重）/
```
high
```
（高危）问题。
可选执行快速开始命令
```
5
```
（
```
--test-only
```
）进行本地执行检查。
执行快速开始命令
```
6
```
（
```
--strict
```
）作为最终合并检查。

必须执行的检查：语法检查 + 安全检查。推荐执行的检查：最佳实践检查。可选检查：本地执行测试。

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.

```
critical
```
（严重）：直接暴露凭证/密钥或存在高风险攻击路径。阻止合并。
```
high
```
（高危）：存在可被利用的不安全行为或严重安全倒退。合并前必须修复。
```
medium
```
（中危）：存在安全加固缺口且有实际风险。需跟踪并尽快修复。
```
low
```
（低危）/
```
suggestion
```
（建议）：优化或可维护性改进建议。

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.

语法规则（
```
yaml-syntax
```
、
```
job-stage-undefined
```
、
```
dependencies-undefined-job
```
）：防止流水线解析失败和依赖错误。
最佳实践规则（
```
cache-missing
```
、
```
artifact-no-expiration
```
、
```
dag-optimization
```
）：降低运行成本并提升流水线吞吐量。
安全规则（
```
hardcoded-password
```
、
```
curl-pipe-bash
```
、
```
include-remote-unverified
```
）：减少凭证泄露和供应链风险。

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

本地语法参考文档：

devops-skills-plugin/skills/gitlab-ci-validator/docs/gitlab-ci-reference.md

本地最佳实践文档：

devops-skills-plugin/skills/gitlab-ci-validator/docs/best-practices.md

本地常见问题文档：

devops-skills-plugin/skills/gitlab-ci-validator/docs/common-issues.md

GitLab CI YAML 官方参考：https://docs.gitlab.com/ee/ci/yaml/
GitLab CI/CD 组件：https://docs.gitlab.com/ee/ci/components/
GitLab 流水线安全指南：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.

缺少
```
python3
```
：
- 现象：验证工具无法运行。
- 替代方案：安装Python 3后重新运行。
缺少
```
PyYAML
```
：
- 现象：
```
python_wrapper.sh
```
  会尝试自动创建
```
.venv
```
  并安装
```
pyyaml
```
  。
- 受限/离线环境下的替代方案：从内部镜像预安装
```
pyyaml
```
  后重新运行。
缺少
```
gitlab-ci-local
```
、
```
node
```
或
```
docker
```
：
- 现象：
```
--test-only
```
  参数会返回警告/失败。
- 替代方案：跳过本地执行测试，继续执行语法/最佳实践/安全检查。
脚本无执行权限：
- 现象：出现Shell权限错误。
- 替代方案：重新执行安装部分的
```
chmod
```
  命令。

Examples

示例

Example 1: New Pipeline Validation

示例1：新流水线验证

bash

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

bash

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

Example 2: Pre-Merge Hard Gate

示例2：合并前强制检查

bash

$VALIDATOR .gitlab-ci.yml --strict

bash

$VALIDATOR .gitlab-ci.yml --strict

Example 3: CI Integration

示例3：CI集成

yaml

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

yaml

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)

独立验证器（进阶用法）

bash

undefined

bash

undefined

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

undefined

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

undefined

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.

前端部分的
```
name
```
和
```
description
```
保持不变。
统一使用标准化的工具调用路径。
安装步骤和
```
chmod
```
前提条件位于流程/示例之前。
快速开始命令与流程无重复（流程引用快速开始的检查步骤）。
明确说明规则严重程度的依据及对应文档链接。
记录工具缺失或环境受限时的替代方案。
示例可从仓库根目录直接执行。

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.

本技能仅验证配置和静态模式，不执行生产流水线。
如需确认运行时行为，请使用
```
gitlab-ci-local
```
或GitLab CI Lint工具。