GitLab CI/CD 基本用法指南

GitLab CI/CD 基本用法指南

一、流水线触发方式

GitLab CI/CD 流水线可以通过多种方式触发，常见的触发方式如下：

触发方式	$CI_PIPELINE_SOURCE 的值	说明
代码推送（Push）	push	向仓库推送代码时自动触发
合并请求（MR）	merge_request_event	创建或更新合并请求时触发
网页手动触发	web	在 GitLab 网页上点击 "Run Pipeline" 按钮触发
定时触发	schedule	通过 CI/CD Schedules 定时任务触发
API 触发	api	通过 GitLab API 调用触发
上游流水线触发	pipeline	由另一个项目的流水线触发（跨项目）
父子流水线触发	parent_pipeline	由同一项目内的父流水线触发

---

二、workflow: rules --- 控制流水线是否创建

workflow: rules 是顶层配置 ，用于控制整条流水线是否被创建。

支持的 when 值

when 值	含义
always	创建流水线（默认值，可省略）
never	不创建流水线

⚠️ 注意：when: manual 不能用在 workflow: rules 里！ 流水线只有"创建"和"不创建"两种状态，没有"手动创建"这个概念。

写法一：白名单模式（推荐用于严格管控）

明确列出允许的情况，其他一律拒绝：

workflow:
  rules:
    # 只在手动触发时创建流水线
    - if: '$CI_PIPELINE_SOURCE == "web"'
    # 其他情况一律不创建
    - when: never

效果：只有通过网页手动点击 "Run Pipeline" 才能创建流水线，代码推送、MR 等都不会触发。

写法二：黑名单模式（推荐用于灵活放行）

明确列出排除的情况，其他默认允许：

workflow:
  rules:
    # 草稿提交不触发
    - if: '$CI_COMMIT_MESSAGE =~ /-draft$/'
      when: never
    # 定时任务不触发
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
      when: never
    # MR 事件不触发
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: never
    # 其他情况都允许
    - when: always

效果：除了上面列出的三种情况外，其他所有触发方式都会创建流水线。

如何选择？

场景	推荐模式
只允许少数特定方式触发	✅ 白名单模式 （列出允许项 + when: never 兜底）
默认允许，只排除少数情况	✅ 黑名单模式 （列出排除项 + when: always 兜底）

---

三、job: rules --- 控制单个 Job 是否运行

rules 也可以写在单个 job 内部，用于控制该 job 是否执行、如何执行。

支持的 when 值

when 值	含义
on_success	前置 stage 成功时运行（默认值）
on_failure	前置 stage 失败时运行
always	无论如何都运行
never	不运行
manual	需要手动点击才运行（仅 job 级别支持）
delayed	延迟一段时间后运行

示例：仅在主分支上自动部署，其他分支手动部署

deploy-job:
  stage: deploy
  script:
    - echo "Deploying..."
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: on_success    # 主分支：前置阶段成功后自动运行
    - when: manual         # 其他分支：需要手动点击触发

---

四、workflow: rules vs job: rules 核心差异

对比项	workflow: rules	job: rules
作用范围	整条流水线	单个 Job
控制的是什么	流水线是否创建	Job 是否执行
支持 when: manual	❌ 不支持	✅ 支持
支持 when: delayed	❌ 不支持	✅ 支持
支持 when: on_success	❌ 不支持	✅ 支持
支持 when: on_failure	❌ 不支持	✅ 支持
支持 when: always	✅ 支持	✅ 支持
支持 when: never	✅ 支持	✅ 支持

执行顺序

触发事件 → workflow: rules 判断是否创建流水线
                ↓ (创建)
         各 job 的 rules 判断各自是否执行
                ↓
         按 stage 顺序执行匹配到的 job

一句话总结 ：workflow: rules 是"门卫"，决定流水线能不能进来；job: rules 是"岗位分配"，决定每个人干不干活。

---

五、常用预定义变量

变量	说明
$CI_PIPELINE_SOURCE	流水线触发方式（push、web、schedule 等）
$CI_COMMIT_BRANCH	当前提交所在分支名
$CI_COMMIT_TAG	当前提交的 Tag 名（如果是 Tag 触发）
$CI_COMMIT_MESSAGE	提交信息
$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME	MR 的源分支名
$CI_MERGE_REQUEST_TARGET_BRANCH_NAME	MR 的目标分支名

---

六、完整示例

# 控制流水线创建规则：仅手动触发
workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
    - when: never

stages:
  - build
  - test
  - deploy

build-job:
  stage: build
  tags:
    - windows-builder
  script:
    - echo "Compiling the code..."
    - echo "Compile complete."

unit-test-job:
  stage: test
  tags:
    - windows-builder
  script:
    - echo "Running unit tests..."
    - echo "Code coverage is 90%"

deploy-job:
  stage: deploy
  environment: production
  tags:
    - windows-builder
  script:
    - echo "Deploying application..."
    - echo "Application successfully deployed."

---

参考链接

• GitLab CI/CD YAML 语法参考
• workflow: rules 文档
• 预定义变量列表