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 个
- 跨 stage 依赖必须用
- 重复作业用
parallel:matrix传参并行,禁止手写多个近似 job
缓存与产物规范
- 职责划分:
- cache:缓存依赖与中间产物(
node_modules、~/.m2)以加速构建,内容不可靠、可能失效,禁止作为数据传递通道 - artifacts:跨 stage 传递的构建产物(二进制、测试报告),供下游作业与人工下载
- cache:缓存依赖与中间产物(
- 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
- dind:要求 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以依赖文件指纹生成缓存键,提升缓存命中率