GitLab CI/CD：从 .gitlab-ci.yml 到生产流水线

为什么需要 GitLab CI/CD：CI 与 CD 一体化，无需独立 CI 服务器

没有 CI/CD 时，代码合并靠人工确认、测试靠本地执行、部署靠 SSH 上去手动操作，出现「在我机器上是好的」和「上线回滚靠回忆」的常态。独立 CI 服务器（如自建 Jenkins）解决了自动化问题，却引入新成本：服务器要单独部署维护，构建脚本散落在服务器或插件配置里，无法随代码评审，触发器与代码仓库的关联靠插件拼接。

GitLab CI/CD 把答案收敛在代码仓库本身。配置文件 .gitlab-ci.yml 与代码同库、同提交、同评审，任何一次修改都能在 MR 中看到 diff；推送代码即触发流水线，MR 分支天然获得独立验证，默认按 build → test → deploy 三阶段执行，未通过测试的代码进不了主干。部署侧内置环境（environment）记录、回滚按钮与部署审批，发布历史成为可检索的结构化数据，不再依赖人工记录。

与同类工具相比，GitLab CI/CD 的气质是「平台收敛」：SCM、MR 评审、流水线、制品库、安全扫描同属一个平台，配置一处编写、权限统一管控。GitHub Actions 更强调事件驱动与 Action 市场的开放生态，Jenkins 胜在插件定制的自由度，而 GitLab CI/CD 的核心优势是少组装、开箱即用，特别适合已经在用 GitLab 管理代码的团队。

安装与环境配置：4 步就绪（GitLab.com 免安装）

路径 A：直接用 GitLab.com（推荐先体验）。 注册账号、新建项目即可获得 CI/CD 能力，无需任何安装。注意免费套餐的共享 Runner 额度政策多次调整，2023 年后新建私有项目基本不再默认赠送共享 Runner 计算时长，生产使用建议自托管 Runner。

路径 B：自托管 GitLab + 自己的 Runner。 按以下步骤操作：

步骤一：安装 GitLab 服务端（Ubuntu 22.04 示例）。 官方提供的 apt 仓库脚本会配置软件源，随后设置对外 URL 并安装，安装后服务自动启动，浏览器访问 https://gitlab.example.com 完成 root 密码初始化。

步骤二：安装 GitLab Runner。 Runner 是真正执行流水线 job 的代理程序，需要与 GitLab 服务端分开安装。安装后可用 gitlab-runner --version 确认版本。

步骤三：注册 Runner。 在项目「设置 → CI/CD → Runner」中获取注册令牌（token），执行注册命令。--executor docker 表示每个 job 在独立容器中运行，隔离性好，是生产最常用方案。

步骤四：验证。 执行 gitlab-runner verify 查看 Runner 是否在线，再提交一个含 .gitlab-ci.yml 的提交触发冒烟流水线。

# 1. 安装 GitLab（Ubuntu，企业版包，社区版将 gitlab-ee 换为 gitlab-ce）curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bashsudo EXTERNAL_URL="https://gitlab.example.com" apt-get install gitlab-ee # 2. 安装 Runnercurl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bashsudo apt-get install gitlab-runner # 3. 注册 Runner（token 在项目/组/实例的设置中获取）sudo gitlab-runner register \  --url https://gitlab.example.com \  --token "$RUNNER_REGISTRATION_TOKEN" \  --executor docker \  --docker-image alpine:latest # 4. 验证sudo gitlab-runner verify

快速上手：10 分钟跑通第一个流水线

最小可用流程的思路：一个 YAML 文件 + 一次推送 = 一条可观察的流水线。不需要先搞懂全部关键字，先把「提交 → 自动测试 → 自动构建 → 手动部署」这条骨架立起来，再逐步加规则。

步骤一：新建项目。 在 GitLab 上创建空白项目，语言选任何你熟悉的即可；CI/CD 不依赖项目语言。

步骤二：创建 .gitlab-ci.yml。 在项目根目录创建该文件，或打开「构建 → 流水线编辑器」（Pipeline Editor）在线编写。编辑器自带语法高亮与 CI Lint 校验，保存前即可发现 YAML 与关键字错误，是官方推荐入口。

步骤三：编写最小流水线。 复制下面的三段式示例：test 与 build 在推送时自动执行，deploy 仅当推送到默认分支（main）时出现，且需要人工点击确认（when: manual）——这是生产环境常见的「人控门禁」。

步骤四：提交并观察。 推送到仓库后，打开「构建 → 流水线」查看运行状态，点击 job 看实时日志；job 失败会以非零退出码标记为红色。

进阶技巧：在流水线编辑器右侧的 CI Lint 中可对任意分支的配置做离线校验；想验证「只跑某个 job」可勾选 job 旁的运行按钮；pytest 等命令建议放到项目自带的环境（Docker 镜像的 image 关键字）中，保证本地与 CI 行为一致。

# .gitlab-ci.yml（最小可用示例，script 替换为项目真实命令）stages:           # 未声明时默认 build → test → deploy  - test  - build  - deploy test:  stage: test  script:    - echo "running tests"    - pytest          # 按项目实际测试命令替换 build:  stage: build  script:    - docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" . deploy:  stage: deploy  environment: production    # 记录部署环境，可在界面查看历史与回滚  script:    - echo "deploying to production"  rules:    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH      when: manual           # 默认分支上手动点击才部署

核心能力详解：6 大支柱

支柱一：流水线编排与规则引擎。 默认模型是「阶段串行、阶段内 job 并行」：后一阶段等待前一阶段全部结束。需要提速时用 needs 声明直接依赖，构成 DAG（有向无环图，即 job 之间只按依赖关系串行、互不依赖的并行执行），配合 rules: if/changes/exists 按分支、文件变动或流水线来源（推送、MR、定时、API 触发）决定是否运行；workflow: rules 可全局控制整条流水线的启停条件。

支柱二：Runner 与执行器。 Runner 分为共享（实例/组级）、项目级三类，用 tags 指定某个 job 必须由哪类 Runner 执行。执行器（executor）决定 job 的运行环境：shell 直接在宿主机执行，docker 每个 job 起独立容器，kubernetes 由集群动态调度 Pod，另有 ssh、virtualbox、parallels 等。生产推荐 docker 或 kubernetes，依赖隔离且扩展性好。

支柱三：制品与缓存。 artifacts（构建产物，如编译结果、测试报告）会在 job 成功后被 GitLab 收集，按 dependencies 指定的依赖关系传给下一阶段，也可在页面直接下载；cache 则缓存依赖目录（如 node_modules、PyPI 缓存）以加速后续运行。两者不能混用：文件跨 job 传递只能靠 artifacts，cache 只是「尽力而为」的加速手段，不保证存在。

支柱四：环境、部署与回滚。 environment: production 把 job 与部署环境绑定，流水线页会生成环境列表、每次部署对应的提交与时间线；问题版本可一键回滚到上一成功部署。动态环境（如 review apps）用 $CI_COMMIT_REF_SLUG 等预定义变量为每个 MR 生成临时环境，MR 关闭即回收。企业版还支持部署审批与保护环境，生产环境部署需指定角色批准。

支柱五：变量与凭据安全。 变量优先级从高到低为：触发器/定时流水线变量 → 项目变量 → 组变量 → 实例变量 → .gitlab-ci.yml 中定义的变量 → 系统预定义变量（CI_COMMIT_SHA、CI_PIPELINE_ID、CI_REGISTRY_IMAGE 等）。敏感值用「受保护变量」（仅受保护分支/标签可见）与「掩码变量」（日志中自动打码）；job 间凭据传递用 CI_JOB_TOKEN，默认只可访问当前项目，跨项目访问需在「设置 → CI/CD → Job token 权限」显式授权。

支柱六：CI/CD 组件与复用。 include 支持 local（同仓库）、project（跨仓库文件）、remote（URL）、template（官方模板）四种引用方式；更进一步是 CI/CD 组件（components），把一组 job/脚本封装成带版本的单元，通过 include: component: gitlab.com/namespace/project/component@版本 引入，适合多项目共享流水线逻辑。

生产部署与监控：从上线到运维

部署方式一：GitLab.com + 自托管 Docker Runner。 团队用官方 SaaS 托管代码，Runner 部署在自己的云主机或内网，适合中小团队快速上线、且对代码托管无合规约束的场景。Runner 机器建议独立于业务机器，按项目打 tag 隔离并发。

部署方式二：Kubernetes 集群 + Runner Helm 部署。 在已有 K8s 集群中使用官方 Helm Chart 部署 Runner，执行器选 kubernetes，job 作为 Pod 由集群调度，按队列自动扩缩。适合已经容器化的中大规模团队，CI 与线上环境共享基础设施、也可用独立节点池隔离。

可观测性。 单条流水线在「构建 → 流水线」/「流水线编辑器」按阶段查看每个 job 的实时日志、时长与退出码；制品文件可在 job 详情页浏览下载。「构建 → CI/CD 分析」聚合仓库维度的流水线平均时长、成功率和失败趋势，适合周会复盘。「项目 → 设置 → Webhooks」把流水线事件推给监控/IM 系统，也可通过 REST API（/projects/:id/pipelines）拉取状态做外部大盘。Runner 自身暴露 Prometheus metrics（默认 9252 端口），可纳入集群监控告警。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>坑 1：rules 与旧式 only/except 混用。两者同时出现时按 GitLab 固定合并规则生效，极易写出「看似生效实则跳过」的 job。官方文档明确推荐只用 rules，旧的 only/except 是遗留语法。</li><li>坑 2：把 cache 当 artifacts 用。cache 只是「尝试恢复」的加速缓存，新 Runner 或缓存被清理时文件不保证存在；跨 job 传递必需文件请用 artifacts + dependencies。</li><li>坑 3：shell executor 跑在共享宿主机。多个项目的 job 在同一台机器、同一文件系统上执行，环境互相污染、权限难隔离且有安全风险。生产至少用 docker executor，最好用 kubernetes。</li><li>坑 4：制品与大镜像不限量保留。artifacts 默认 30 天失效但仍占用存储，频繁构建的镜像仓库会持续膨胀；设置合理的 expire_in（如 1 周）并在容器仓库配置清理策略。</li><li>坑 5：忽略 GIT_STRATEGY 与克隆开销。每次 job 默认全量 clone 仓库，提交频繁时会显著拖慢流水线；改为 fetch（增量拉取）可减少传输，必要时用 shallow clone 控制深度。</li></ul>

helm repo add gitlab https://charts.gitlab.iohelm install gitlab-runner gitlab/gitlab-runner \  --set gitlabUrl=https://gitlab.example.com \  --set runnerRegistrationToken="$RUNNER_REGISTRATION_TOKEN" \  --set rbac.create=true

版本迭代

GitLab 自 2018 年起按月发布新版本，每年 5 月左右发布一次「00」结尾的年度大版本。近三年主线是：15.x 完善流水线编辑器与 DAG 并行体验，16.x 强化合并请求内验证，17.x 大规模清理遗留语法并推进 CI/CD 组件复用，18.0 延续组件生态并移除到期废弃项。（截至训练数据，18.0 后可能已有更新版本）

AI 应用场景

常见误区

面试题

参考来源

• webpage.gitlab-ci.yml 关键字参考每个配置关键字的语法与示例
• webpageGitLab 官方发布说明每月新功能、变更与升级公告