.gitlab-ci.yml 是什么
GitLab 流水线的配置文件，放在仓库根目录：声明 stages 与作业（job），每个作业指定 stage、script 与运行条件，作业名即流水线界面中的显示名。不声明 stages 时使用 build、test、deploy 三阶段兜底。全局键（default、workflow、include、variables、stages）与作业键（stage、script、image、rules、needs、artifacts、cache、tags）构成完整语义。结构决定顺序：阶段之间串行、同阶段作业并行，needs 可把串行关系改写成 DAG。
基本信息
| 位置 | 仓库根目录 .gitlab-ci.yml |
|---|---|
| 默认阶段 | 未声明 stages 时使用 build、test、deploy |
| 作业核心键 | stage、script、image、rules |
| 全局键 | default、workflow、include、stages、variables |
| 执行细节 | 同一作业的 script 各行在同一 shell 会话中执行 |
典型使用场景
- 从零建流水线：按最小结构先跑通 build 与 test，再逐项加规则与产物。
- 多项目复用：include 引入共享模板，避免每个仓库重复维护同一套作业。
- 多环境部署：用 environment 记录部署历史，deploy 作业按分支或标签限定。
- 触发治理：workflow:rules 统一控制何时创建流水线，例如仅合并请求与主干。
- 测试分片：parallel 或 matrix 展开分片，减少整体墙钟时间。
- 权限控制：tags 把作业定向到专用 Runner，敏感作业限定在受保护分支。
- 渐进迁移：only/except 迁移到 rules 时逐作业对齐行为，稳定后再删除旧语法。
最小流水线
最小流水线
stages: [build, test, deploy]
build-job:
stage: build
script:
- make build # 产物可在后续作业用 artifacts 声明
test-job:
stage: test
script:
- make test阶段决定作业顺序，同阶段作业默认并行；跨阶段依赖可用 needs 改成 DAG，上游就绪即开始。
作业名是界面显示名与 needs 的引用名：改名等于一次接口变更，相关引用与分支保护检查要同步核对。
script 各行在同一 shell 会话中执行：cd 与 export 会延续到后续行，行与行互相影响，需要隔离时用子 shell 或独立脚本。
常用作业键速查
| 键 | 作用 |
|---|---|
| stage | 声明所属阶段，决定顺序 |
| script | 执行的命令序列，同一 shell 会话 |
| rules | 何时运行、以何种方式运行 |
| needs | 只等指定上游作业，构成 DAG |
| artifacts | 作业产物，供下游下载与留存 |
| cache | 可再生的加速缓存 |
受保护分支与受保护变量联动：变量可限定只在受保护分支或标签的流水线中注入，敏感部署凭据应绑定保护范围。部署凭据配成普通变量时，任何流水线都可能读到。