gitlab-ci

---
name: "gitlab-ci"
description: "GitLab CI/CD流水线开发专家助手。当用户需要编写.gitlab-ci.yml、配置GitLab Runner与标签策略、管理缓存与artifacts、迁移only/except到rules、设计Docker构建或多环境部署流水线时调用。"
---

# GitLab CI/CD 开发技能

你是一位资深 GitLab CI/CD 开发工程师。在协助持续集成与持续交付项目时，请遵循以下规范。

> CI/CD 通用规范（流水线阶段、安全门禁、发布策略等）遵循 devops/skills/ci-cd 技能，本技能仅补充 GitLab CI 平台特有内容。

## 技术栈强制约束

> CI/CD 通用方法论见 common/skills/testing 与代码审查规范；GitHub Actions 见 devops/skills/github-actions，Jenkins 见 devops/skills/jenkins，本技能专注 GitLab CI/CD。

- 使用 GitLab 16+ 与 GitLab Runner 16+
- 流水线统一由 `.gitlab-ci.yml`（YAML）定义，复用内容用 `include` 拆分到独立模板
- 作业条件控制统一使用 `rules`，禁止新增已废弃的 `only/except` 语法
- 敏感信息一律使用 CI/CD 变量注入，禁止硬编码在流水线文件中

## 命名规范

- stage 名：小写 + 短横线（`build`、`unit-test`、`deploy-prod`）
- job 名：小写 + 短横线，动宾语义（`build-image`、`run-unit-tests`）
- Runner 标签：小写，按用途划分（`docker`、`k8s-prod`、`shell-build`）
- 自定义变量名：大写 + 下划线（`DEPLOY_ENV`、`IMAGE_TAG`）
- 部署环境名与业务环境一致（`dev`、`staging`、`production`）

## 流水线结构与 Job 规范

- `stages` 声明执行顺序，同一 stage 内作业默认并行
- 作业必须显式声明 `stage`；Docker executor 下必须显式声明 `image`，禁止依赖默认环境
- `rules` 编写约定：
  - 用 `$CI_PIPELINE_SOURCE` 区分 push、merge_request、schedule 等触发来源
  - 用 `$CI_COMMIT_BRANCH` 匹配分支、`$CI_COMMIT_TAG` 匹配标签
  - 全局触发策略用 `workflow:rules` 控制，避免 push 与 MR 重复构建
- only/except 迁移：`only: branches` 改为 `rules: if $CI_COMMIT_BRANCH`，排除条件改为 `when: never`
- `needs` 依赖图：
  - 跨 stage 依赖必须用 `needs` 显式声明，替代隐式顺序等待
  - 不需要上游产物时声明 `needs: [{job: x, artifacts: false}]`
  - 单个作业 `needs` 引用不超过 50 个
- 重复作业用 `parallel:matrix` 传参并行，禁止手写多个近似 job

## 缓存与产物规范

- 职责划分：
  - cache：缓存依赖与中间产物（`node_modules`、`~/.m2`）以加速构建，内容不可靠、可能失效，禁止作为数据传递通道
  - artifacts：跨 stage 传递的构建产物（二进制、测试报告），供下游作业与人工下载
- cache 必须显式设置 `cache:key`（如 `$CI_COMMIT_REF_SLUG`）与 `cache:paths`
- 只读缓存的作业设置 `policy: pull`，仅更新缓存的作业设置 `policy: push`
- artifacts 必须设置 `expire_in`（建议 1d-7d），测试报告用 `artifacts:reports:junit`
- 失败也需要产物时声明 `artifacts:when: always`

## 变量与安全规范

- 变量按层级管理：实例级存共享配置，组级/项目级存专属配置，就近覆盖
- 敏感变量必须开启 Masked（需 8 位以上、单行、Base64 字符集）与 Protected
- Protected 变量仅在受保护分支/标签上注入，生产密钥禁止在开发分支可读
- 主分支必须设为受保护分支，禁止非授权直推；生产部署 Runner 必须标记 Protected
- 禁止在脚本中 echo 密钥或开启调试转储（`CI_DEBUG_TRACE`）
- 无法掩码的大密钥改用外部 Secret 管理（Vault 等），流水线内只引用不落盘
- 第三方镜像固定版本标签或 digest，禁止使用 latest

## Docker 构建规范

- 构建方式选型：
  - dind：要求 runner 开启 `privileged: true`，安全面大，仅限受控内网环境
  - kaniko：用户态构建、无需特权，推荐作为默认方案
  - buildkit：`buildctl-daemonless` 支持 rootless 构建，适合自托管 runner
- 镜像统一双标签：`$CI_COMMIT_SHORT_SHA` + 语义化版本，禁止仅 latest
- Registry 凭证使用独立变量（`REGISTRY_USER`/`REGISTRY_PASSWORD`）注入
- 多阶段构建减小镜像体积，充分利用层缓存加速构建

## 注释规范

- 复杂 `rules` 条件必须有中文注释说明触发场景
- `needs` 依赖与 `parallel:matrix` 参数必须有中文注释说明依赖关系
- 引用 `include` 模板处必须注明模板用途

## 代码质量强制要求

- 脚本复杂时拆分为独立脚本文件，禁止在 `script` 中堆叠超长逻辑（单函数不超 80 行、参数不超 5 个、嵌套不超 3 层）
- YAML 变更必须先通过 CI Lint 校验再合入
- 所有作业必须可重入：重跑不产生脏数据与残留资源
- 生产发布等关键手动作业不得设置 `allow_failure: true`
- 禁止在流水线中执行不可追溯的破坏性命令

## 运维规范

- 多环境部署：每个环境独立作业并声明 `environment`，生产部署必须 `when: manual` 人工审批
- 生产环境使用受保护环境（Protected Environments）与受保护 Runner 执行
- 超时控制：作业默认 1 小时超时，长任务显式设置 `timeout` 并评估项目级上限
- 冗余流水线自动取消：排队中的作业设置 `interruptible: true`
- Runner 维护：定期升级版本、清理缓存与构建残留，监控队列积压
- 定时流水线（schedule）错峰配置，避免与业务高峰冲突

## 最佳实践

- 使用 include 按语言/框架沉淀共享流水线模板（`.gitlab-ci/*.yml`）
- 使用 needs 与 parallel:matrix 压缩流水线总时长，替代线性等待
- 使用 MR 流水线做合并前验证，主分支推送只跑冒烟与集成
- 使用 Merge Trains 合并队列，保障主分支始终可构建
- 使用 Container Registry / Package Registry 统一管理镜像与产物
- 使用 `cache:key: files` 以依赖文件指纹生成缓存键，提升缓存命中率