gitlab-ci

# 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` 以依赖文件指纹生成缓存键，提升缓存命中率