📚 课程目录第2章 GitLab CI基础回顾

GitLab CI 基础回顾：.gitlab-ci.yml 结构、Job/Stage/Runner 概念、Pipeline 触发方式

在深入跨项目适配之前，必须牢固掌握 GitLab CI 的核心基础。本章将系统梳理 .gitlab-ci.yml 的声明式结构、Job/Stage/Runner 三大核心概念，以及 Pipeline 的多种触发方式。这些基础是后续构建服务目录、实现跨项目调用的基石。

1. .gitlab-ci.yml 结构解析

.gitlab-ci.yml 是 GitLab CI 的“单一事实来源”，采用 YAML 格式定义整个流水线。一个典型的流水线文件包含以下顶层关键字：

关键字	作用	是否必填
`stages`	定义流水线的阶段顺序，如 `build`、`test`、`deploy`	推荐
`job_name`	定义具体任务，包含 `stage`、`script`、`image` 等子字段	是
`before_script`	在每个 Job 执行前运行的脚本，常用于安装依赖或设置环境	否
`after_script`	在每个 Job 执行后运行的脚本，常用于清理或通知	否
`variables`	定义全局或 Job 级别的 CI/CD 变量	否
`cache`	缓存依赖文件，加速后续 Job 执行	否
`include`	引入外部 YAML 文件，实现流水线复用（跨项目适配的关键）	否

  关键原则：Job 是流水线的最小执行单元；stages 定义执行顺序；include 是实现流水线服务目录复用的核心机制。

以下是一个基础示例：

stages:
  - build
  - test
  - deploy

variables:
  APP_VERSION: "1.0.0"

before_script:
  - echo "Starting pipeline for $CI_PROJECT_NAME"

build-job:
  stage: build
  script:
    - echo "Compiling application..."
    - mkdir -p build/
    - echo "Build complete" > build/output.txt
  artifacts:
    paths:
      - build/

test-job:
  stage: test
  script:
    - echo "Running unit tests..."
    - cat build/output.txt
  dependencies:
    - build-job

deploy-job:
  stage: deploy
  script:
    - echo "Deploying version $APP_VERSION"
  only:
    - main

2. Job / Stage / Runner 核心概念

理解这三者的关系是掌握 GitLab CI 的关键。它们分别对应“做什么”、“何时做”和“在哪做”。

Job（任务）：流水线的基本执行单元。每个 Job 必须包含 script 字段，定义要执行的命令。Job 可以设置 stage、image、tags、only/except 等属性。
Stage（阶段）：Job 的逻辑分组，定义执行顺序。同一 Stage 内的 Job 默认并行执行；不同 Stage 按 stages 列表顺序串行执行。如果某个 Stage 中的 Job 失败，默认后续 Stage 不会执行。
Runner（执行器）：实际运行 Job 的代理程序。Runner 可以安装在物理机、虚拟机、容器或 Kubernetes 集群上。通过 tags 字段将 Job 分配给特定 Runner。

最佳实践：在跨项目适配场景中，建议为 Runner 打上明确的标签（如 docker、k8s、high-mem），以便在服务目录中精确调度执行环境。

3. Pipeline 触发方式

GitLab CI 支持多种触发 Pipeline 的方式，理解这些触发机制对于设计跨项目服务目录至关重要。以下是主要的触发方式对比：

触发方式	触发条件	典型场景	跨项目适用性
Push 触发	代码推送到仓库	开发分支提交后自动构建测试	基础触发，服务目录项目自身更新
Merge Request 触发	创建或更新 MR	MR 预合并验证、代码审查流水线	可用于验证服务目录变更
Schedule 定时触发	CRON 表达式定时执行	每日构建、夜间回归测试	可用于定期同步服务目录
API 触发	调用 GitLab Pipeline API	外部系统触发部署、CI/CD 链式调用	核心方式，跨项目调用服务目录
Multi-Project Pipeline	上游项目完成时触发下游项目	微服务间依赖构建、端到端测试	核心方式，服务目录编排
Webhook 触发	外部 Webhook 请求	与第三方系统集成（如 Jenkins、Jira）	可用于扩展服务目录入口

注意：在跨项目适配中，API 触发 和 Multi-Project Pipeline 是最常用的两种方式。API 触发适合按需调用服务目录中的某个 Job；Multi-Project Pipeline 适合编排完整的跨项目流水线流程。

4. 跨项目适配视角下的基础回顾

在服务目录的跨项目适配场景中，上述基础概念有以下关键映射：

.gitlab-ci.yml 结构：服务目录项目通过 include 关键字将公共 Job 定义暴露给消费项目，消费项目只需引入即可复用。
Job/Stage/Runner：服务目录中的每个 Job 应设计为原子化、可参数化的“服务单元”；Stage 用于编排服务调用顺序；Runner 标签确保服务在正确的环境中执行。
Pipeline 触发：消费项目通过 API 触发 或 Multi-Project Pipeline 调用服务目录中的 Job，实现跨项目流水线编排。