GitLab CI Linter

对 GitLab CI/CD 流水线文件进行语法错误、安全问题、已弃用模式及违背最佳实践等问题的检查。

命令

所有命令均调用内置 Python 脚本 scripts/gitlab_ci_linter.py。

1. 检查流水线文件

python3 scripts/gitlab_ci_linter.py lint <文件或目录> [--strict] [--format text|json|markdown]

对一个或多个 .gitlab-ci.yml 文件运行全部 lint 规则。若传入目录，则递归扫描所有 *.yml 和 *.yaml 文件。

参数说明：

• --strict —— 遇到任意警告（不仅限于错误）即返回退出码 1
• --format —— 输出格式：text（默认）、json、markdown

2. 安全性审计

python3 scripts/gitlab_ci_linter.py security <文件> [--format text|json|markdown]

聚焦于安全性问题：硬编码密钥（如密码、Token、密钥）、未受保护的变量、特权 runner、使用不安全的 Docker 镜像标签（例如 :latest）、设置了 allow_failure 的安全相关 job。

3. 检查 stages

python3 scripts/gitlab_ci_linter.py stages <文件> [--format text|json|markdown]

列出已定义的 stages 及各 stage 所关联的 jobs，并标出未定义或未被使用的 stage。

4. 验证流水线结构

python3 scripts/gitlab_ci_linter.py validate <文件> [--format text|json|markdown]

仅做结构验证：检查必需字段是否存在、stage 是否正确定义、job 关键字是否合法、依赖图是否成环（如 needs: 循环引用）、是否存在缺失的 ref 引用等。

Lint 规则（共 24 条）

语法与结构（8 条）

1. missing-stages —— 缺少 stages: 定义
2. undefined-stage —— job 使用了未在 stages: 列表中声明的 stage
3. empty-job —— job 中无 script: 区块
4. invalid-job-name —— job 名称以 . 开头，但并未作为模板使用
5. missing-script —— job 缺少 script:、before_script: 或 trigger:
6. circular-needs —— needs: 依赖图中存在循环引用
7. duplicate-job —— 存在重复的 job 名称（YAML 解析器会将其合并）
8. invalid-keyword —— 使用了未知的顶层关键字或 job 级关键字

安全性（6 条）

9. hardcoded-secret —— 密码、Token、密钥等以明文形式出现在配置中
10. unprotected-variable —— 敏感特征明显的变量未使用 $CI_* 形式引用
11. allow-failure-security —— 安全相关 job 设置了 allow_failure: true
12. privileged-runner —— tags: 中请求特权 runner
13. unmasked-variable —— 变量疑似敏感，但未标记为 masked
14. insecure-image —— Docker 镜像使用了 :latest 标签

最佳实践（10 条）

15. missing-retry —— 部署或测试类 job 缺少 retry: 配置
16. missing-timeout —— job 未设置 timeout:
17. no-cache-key —— cache: 中未显式指定 key:
18. broad-artifacts —— artifacts: paths: 模式过于宽泛
19. missing-rules —— job 缺少 rules: 或 only:/except:
20. deprecated-only-except —— 使用 only:/except: 而非推荐的 rules:
21. long-script —— script: 区块超过 30 行
22. missing-interruptible —— 长时间运行的 job 未设置 interruptible:
23. no-coverage-regex —— 测试 job 缺少 coverage: 正则表达式
24. missing-when —— rules: 条目中缺少 when:

输出格式

Text（默认）

.gitlab-ci.yml:12 error [missing-script] Job 'deploy' has no script:, before_script:, or trigger:
.gitlab-ci.yml:25 warning [missing-timeout] Job 'test' has no timeout: specified
.gitlab-ci.yml:31 info [deprecated-only-except] Job 'build' uses only:/except: instead of rules:

3 issues (1 error, 2 warnings)

JSON

{
  "file": ".gitlab-ci.yml",
  "issues": [...],
  "summary": {"errors": 1, "warnings": 2, "info": 0}
}

Markdown

以表格形式汇总结果，包含严重等级（severity）、规则名（rule）、位置（location）和提示信息（message）。

CI 集成

# .gitlab-ci.yml
lint-pipeline:
  stage: test
  script:
    - python3 scripts/gitlab_ci_linter.py lint .gitlab-ci.yml --strict

退出码说明：0 表示无问题；1 表示发现错误（或在 --strict 模式下发现警告）。