1. 心智模型：协调器、执行器与一次 pipeline
当你 push 或打开 MR，GitLab 读取默认分支或 MR 源分支上的 CI 配置，生成一条 Pipeline。 Pipeline 按 stage 顺序推进；同一 stage 内的多个 job 默认并行。 真正跑命令的是注册到 GitLab 的 Runner：它向 GitLab 拉取任务、准备环境、执行 script、回传日志与退出码。
2. .gitlab-ci.yml：最小可运行骨架
配置文件通常放在仓库根目录（也可用 include 拆文件）。stages 定义顺序； 每个顶层键（除特殊键外）默认是一个 job 名，内含 stage、script 等。 未指定镜像时，Runner 的执行器决定环境（例如 docker 默认镜像、shell 则用机器环境）。
stages:
- build
- test
variables:
NODE_VERSION: "20"
default:
image: node:${NODE_VERSION}-alpine
before_script:
- node --version
build_app:
stage: build
script:
- npm ci
- npm run build
unit_tests:
stage: test
script:
- npm ci
- npm test
3. Stages 与 Job：铁路时刻表与并行月台
把 stage 想成“时刻表上的大站”：必须先完成 build 这一站的所有必要 job（除非失败策略不同）， 再进入 test。同一站台上，多趟列车可以同时发车——同一 stage 的 job 并行执行。 若需要跨 stage 的精细依赖（不必等整个 stage），后续会用到 needs（第 41 章会与 artifacts 一起深入）。
4. Job 关键词速查（入门必备）
下列关键词在入门阶段最常遇到；与 GitHub Actions 对照时，可粗略记忆：script ≈ steps 里的 run， image ≈ runs-on + container，services ≈ 侧车容器（如数据库）。
- image：Docker 执行器下使用的镜像。
- before_script / after_script：包裹主 script，适合准备环境或收尾上传。
- script：主命令序列；非零退出码通常记为失败。
- tags：挑选带对应 tag 的 Runner（例如 gpu、windows）。
- allow_failure：允许该 job 失败而不阻断后续 stage（慎用，需配合质量文化）。
- timeout：防止卡死占用 Runner；与成本、队列公平性相关。
5. GitLab Runner：谁能接你的单？
Runner 分共享与专用：SaaS GitLab.com 提供 Shared Runners；自建实例常注册 Group / Project 级 Runner。 治理关注点包括：隔离（多租户是否可信）、机密（变量与宿主机边界）、容量（并发与队列）、合规（数据是否出境）。
6. 内置变量与可观测性
GitLab 注入大量只读的 CI_* 变量（如 CI_COMMIT_SHA、CI_PIPELINE_ID、 CI_JOB_NAME）。在 script 里用 shell 引用即可，便于打标签、拼镜像名、写审计日志。 Pipeline 页面展示每个 job 的日志、耗时、重试——把“可观测”当作一等公民，排障会快一个数量级。
print_ids:
stage: build
script:
- echo "Commit $CI_COMMIT_SHA pipeline $CI_PIPELINE_ID"
- echo "Running job $CI_JOB_NAME on $CI_RUNNER_DESCRIPTION"
7. CI Lint 与拆分配置
在合并前用 CI Lint（UI 或 API）校验 YAML：阶段是否自洽、job 名是否冲突、include 是否可达。 大仓库常用 include: local / project / template 把基座模板与业务 job 分离，减少复制粘贴灾难。
8. 与 GitHub Actions 的粗略对照
两者都是“YAML 声明式流水线”，差异主要在生态与概念命名：GitLab 把 Runner 一概念摆到台前；GitHub 则强调 Marketplace action 与可复用 workflow。 学会本章后，你读 Actions 的 workflow 会更快，反之亦然。
| Topic | GitLab CI | GitHub Actions |
|---|---|---|
| Config file | .gitlab-ci.yml (+ include) | .github/workflows/*.yml |
| Compute | GitLab Runner (registered) | GitHub-hosted or self-hosted runner |
| Grouping | stages + jobs | Jobs in a workflow; needs for DAG |
| Reuse | include, extends, templates | Reusable workflow, composite action |
9. 入门清单
- 写出含 stages、至少两个 job 的最小流水线，并在 UI 中验证 stage 顺序与并行。
- 弄清团队使用的是 Shared 还是专用 Runner；为特殊任务配置 tags。
- 在 script 中打印关键 CI_* 变量，建立“可观测”习惯。
- 合并前跑 CI Lint；计划将公共模板抽到 include。
- 阅读官方文档中关于执行器（docker vs shell）的安全提示，再开放自托管 Runner。