GitLab CI/CD 最佳实践

1. Pipeline 设计最佳实践（核心）

1.1 使用 Stage 构建标准 CI/CD 流水线结构

推荐标准三段式：

stages:
  - lint
  - test
  - build
  - deploy

理由：

linters 提前失败 -> 节省 Runner 资源
单元测试通过后才允许打包
最后才触发部署

1.2 一个 Job 做“一类事”，保持最小职责

❌ 反例：在同一个 job 里 lint + test + build
✅ 推荐：每个 job 独立，如 lint, unit_test, build_image

1.3 Job 要可重复执行（幂等）

避免：

修改本地状态
写入共享目录
依赖上一次构建

1.4 所有构建依赖必须写入 image 或 before_script

确保 Runner、机器差异不会影响构建：

image: python:3.12

before_script:
  - pip install -r requirements.txt

1.5 使用 Cache 加速

典型用法：

cache:
  paths:
    - .cache/pip/

不要缓存 build 产物（artifact 适合这个场景）。

2. GitLab CI YAML 最佳实践

2.1 使用 YAML Anchors 减少重复

.default_job: &default_job
  tags: [docker]
  retry: 2
  before_script:
    - pip install -r requirements.txt

test:
  <<: *default_job
  script:
    - pytest

好处：

✨ 结构更干净
✨ 批量修改成本低

2.2 使用 rules 替代 only/except

rules 可精确控制逻辑：

deploy_prod:
  stage: deploy
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
    - when: manual

比 only: [main] 更灵活（可加条件）。

2.3 使用 needs 启用并行流水线（大幅提升速度）

unit_test:
  stage: test

lint:
  stage: test

build:
  stage: build
  needs: ["unit_test", "lint"]

好处：

test 和 lint 并行
只有 test + lint 成功才 build

2.4 使用 artifacts 传递构建产物

build:
  stage: build
  script:
    - npm run build
  artifacts:
    paths:
      - dist/

不要滥用 artifact，否则 CI 会变慢。

2.5 对外部依赖统一使用 environment 变量

不要把 token、密码写进 YAML。

3. 安全最佳实践

3.1 所有敏感信息必须用 GitLab CI Variables 管理

如：

AWS_KEY
K8S_TOKEN
PROD_DB_PASSWORD

不要写在代码里

不要放在 artifact 中

3.2 限制 Runner 权限（不要用 root runner）

部署用独立 Runner
构建用普通 Runner
避免一个 job 的安全问题影响其他 job

3.3 在 Deploy 使用 Manual + Protected 分支

deploy_prod:
  when: manual
  environment:
    name: production
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

只允许 Maintainer 触发。

4. 性能最佳实践

4.1 尽量使用 Docker Runner（shell runner 尽量不用）

Docker runner 隔离强、安全、可控。

4.2 用 Cache 优化依赖安装

如 Python/Node/Go 都可以缓存依赖。

4.3 拆分 Job 和 Stage 加速执行

比一个超级大 Job 更快且更稳定。

5. 可维护性最佳实践

5.1 所有 CI 配置写入 .gitlab-ci.yml + 单独拆成多个文件

主文件：

include:
  - local: ".gitlab/ci/lint.yml"
  - local: ".gitlab/ci/docker.yml"
  - local: ".gitlab/ci/deploy.yml"

方便管理大型 CI 项目。

5.2 添加描述（description），让 CI 更易读

build:
  stage: build
  description: "构建 Docker 镜像并推送到仓库"

5.3 给 Job 添加 retry

网络波动、偶发失败常见。

retry: 2

6. 质量控制最佳实践

6.1 Lint 永远放在第一阶段

Python -> flake8 / black
JS -> eslint
Go -> go fmt

遇到问题立即 fail 省资源。

6.2 单元测试必须覆盖核心逻辑并生成报告

使用 coverage 工具：

coverage: '/^TOTAL.+?(\d+\%)$/'

6.3 部署前必须构建 + 测试成功（不要允许跳过）

7. 部署最佳实践（K8s / Docker / Server）

7.1 环境配置写 Environment，而不是 hardcode

environment:
  name: staging
  url: https://staging.example.com

7.2 部署必须使用 artifacts 或引用镜像

不要在 Runner 上 build 再部署（不稳定）。

8. 触发器最佳实践

8.1 使用 schedule 做定时任务

如自动构建镜像、定时备份等。

8.2 使用 trigger 构建子项目

微服务项目非常常见：

trigger:
  project: group/subproject
  branch: main

9. Anti-Pattern（禁止出现）

反模式	风险
job 里写多个职责	不可维护，难排错
不使用 cache	CI 超慢
使用 shell runner	不安全
重复拷贝 job 代码	无法维护
把密码写进 .gitlab-ci.yml	安全灾难
随意使用 artifact	CI 变慢，存储膨胀
部署 job 自动执行	误触生产环境

📌 附：最佳实践模板（可直接用）

stages:
  - lint
  - test
  - build
  - deploy

.default: &default
  tags: [docker]
  retry: 2

lint:
  <<: *default
  stage: lint
  script:
    - npm run lint

test:
  <<: *default
  stage: test
  needs: ["lint"]
  script:
    - npm run test

build:
  <<: *default
  stage: build
  needs: ["test"]
  script:
    - npm run build
  artifacts:
    paths:
      - dist/

deploy_prod:
  <<: *default
  stage: deploy
  needs: ["build"]
  when: manual
  environment:
    name: production
  script:
    - ./deploy.sh