GitLab CI/CD 教程

下面是一份完全版 GitLab CI/CD 教程，覆盖核心概念、底层工作机制、关键配置、企业级实践、优化技巧等。

📌 目录

GitLab CI/CD 是什么？
CI/CD 核心概念
.gitlab-ci.yml 文件结构与关键语法
Pipeline（持续集成流程）详解
Jobs、Stages、Rules
GitLab Runner 工作机制
常用 CI 模块（cache、artifacts、needs、variables）
环境（Environments）与部署（Deployments）
GitLab 内置模板与 include
高级功能：并发、依赖、条件构建
Secrets、配置中心、变量管理
CI/CD 进阶优化（速度、缓存、镜像）
生产级项目完整示例
常见问题排查

1. GitLab CI/CD 是什么？

GitLab CI/CD 是 GitLab 内置的持续集成和持续部署系统，用于：

代码自动测试
构建镜像/二进制
部署到服务器/云/K8s
持续检查质量（Lint、审计）

只需要一个文件 .gitlab-ci.yml 就能自动执行整个工作流程。

2. 核心概念（CI 的骨架）

📌 2.1 Pipeline（流水线）

一次 CI 执行即为一个 Pipeline，由多个 Job/stage 组成。

例子：

Pipeline
 ├── build
 ├── test
 └── deploy

📌 2.2 Jobs（任务）

最小 CI 单元，一个 job 代表一段要执行的脚本。

📌 2.3 Stages

Job 分组，按顺序执行：

stages:
  - build
  - test
  - deploy

📌 2.4 Runner

GitLab CI 的执行者，负责运行 Job（前面你已经学过了）。

Runner 执行 .gitlab-ci.yml 内的脚本。

📌 2.5 Artifacts（构件）

某个 job 产生的文件，可被后续 job 下载使用。

📌 2.6 Cache（缓存）

用于加速 Pipeline 速度，如 node_modules/、pip 缓存等。

📌 2.7 Variables（变量）

CI 环境变量，用于配置敏感信息、环境参数。

3. .gitlab-ci.yml 文件结构

基础结构示例：

stages:
  - build
  - test
  - deploy

build_job:
  stage: build
  script:
    - npm install
    - npm run build

test_job:
  stage: test
  script:
    - npm test

deploy_job:
  stage: deploy
  script:
    - ./deploy.sh
  only:
    - main

4. Pipeline 工作流程

Pipeline 执行顺序：

stages 顺序
  -> 同 stage 的 job 并行执行
  -> 下一个 stage

比如：

build（并行）
test（并行）
deploy（并行）

5. Jobs、Stages、Rules（重点中的重点）

5.1 定义 Job

build-job:
  stage: build
  script:
    - go build main.go

5.2 使用 rules 控制 job 触发

比 only/except 更强大的条件匹配系统。

示例：只在 main 分支运行

deploy:
  stage: deploy
  script: ./deploy.sh
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

更复杂：

rules:
  - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  - if: '$CI_COMMIT_BRANCH == "main"'

5.3 needs：真正实现并行（强烈推荐）

test:
  stage: test
  needs: ["build"]

5.4 when（强制、手工）

when: manual

用于生产部署。

6. GitLab Runner 工作机制（简述）

流程：

GitLab 调度 pipeline
匹配 tags -> 找 Runner
Runner 拉取代码
执行 script
产生 artifacts
上报状态给 GitLab

7. 常用 CI 模块（必须掌握）

7.1 cache 缓存

cache:
  paths:
    - node_modules/

7.2 artifacts 构件

artifacts:
  paths:
    - dist/
  expire_in: 1 week

7.3 variables（变量）

variables:
  NODE_ENV: production

7.4 before_script / after_script

整个 pipeline 通用：

before_script:
  - echo "start"

8. 环境（Environment）与自动部署

定义环境：

deploy:
  stage: deploy
  script: ./deploy.sh
  environment:
    name: production
    url: https://example.com

支持：

自动部署
回滚（rollback）
多环境（dev / staging / prod）

9. include 导入模板（推荐）

你可以把 CI 拆分成很多小文件：

include:
  - local: 'ci/build.yml'
  - local: 'ci/test.yml'
  - template: 'Jobs/Build.gitlab-ci.yml'

非常适合大型项目。

10. 高级概念：强大的 CI/CD 机制

10.1 多 Runner 并发处理

利用 tags 分配不同类型任务：

build-job:
  tags: ["docker"]
test-job:
  tags: ["k8s"]

10.2 Matrix 构建（Go / Python 常用）

例如：

test:
  stage: test
  parallel:
    matrix:
      - GO_VERSION: ["1.20", "1.21", "1.22"]

10.3 手动审批

when: manual
allow_failure: false

10.4 依赖缓存（dependencies）

test:
  dependencies:
    - build

11. CI/CD 变量与 Secrets 管理（非常重要）

在 GitLab UI 设置：

Settings -> CI/CD -> Variables

常见敏感信息：

TOKEN
SSH_PRIVATE_KEY
DOCKER_PASSWORD
K8S_CONFIG

在 CI 中使用：

script:
  - echo "$SSH_PRIVATE_KEY" > key.pem

12. CI 优化策略（实战总结）

🚀 12.1 优化镜像

使用语言官方镜像 + cache：

image: python:3.12-slim

🚀 12.2 缓存 node_modules/pip

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - .cache/pip

🚀 12.3 多缓存策略（本地 + S3）

🚀 12.4 尽可能使用 needs: 来并行任务

13. 生产级 .gitlab-ci.yml 示例（最经典的结构）

适用于真实企业项目：

stages:
  - lint
  - build
  - test
  - docker
  - deploy

variables:
  APP: myapp

lint:
  stage: lint
  image: node:20
  script:
    - npm ci
    - npm run lint

build:
  stage: build
  image: python:3.12
  script:
    - pip install -r requirements.txt
    - python build.py
  artifacts:
    paths:
      - build/

test:
  stage: test
  image: python:3.12
  needs: ["build"]
  script:
    - pytest -v

docker-build:
  stage: docker
  tags: ["docker"]
  image: docker:24
  services:
    - docker:dind
  script:
    - docker build -t registry.example.com/$APP:$CI_COMMIT_SHA .
    - docker push registry.example.com/$APP:$CI_COMMIT_SHA

deploy:
  stage: deploy
  tags: ["prod"]
  when: manual
  script:
    - ./deploy_prod.sh

这是生产环境中最常见的 CI/CD 结构。

14. 常见问题排查

❌ 1. 找不到 Runner

检查你的 job 是否设置了 tags:。

❌ 2. cache 不生效

必须存在同一个 Runner 才有效。

❌ 3. docker build 报权限错误

需要：

privileged = true

❌ 4. .gitlab-ci.yml 验证失败

检查：

CI Lint 工具

GitLab 自带检查工具非常好用。