📚 课程目录第2章 GitLab CI/CD入门

GitLab CI/CD入门：.gitlab-ci.yml文件结构、Runner配置、Job与Stage

不管你是刚接触 Android 打包，还是已经在用 Jenkins，GitLab CI/CD 这套东西你迟早要碰。我个人觉得，它最大的好处是「配置即代码」——整个流水线都写在一个 YAML 文件里，跟项目代码放一起，版本管理、团队复用都方便。这一章我们就把最核心的三个概念讲清楚：.gitlab-ci.yml 怎么写、Job 和 Stage 怎么组织、Runner 怎么配。嗯，别急，一个一个来。

.gitlab-ci.yml 文件结构

说白了，这个文件就是流水线的「剧本」。你定义好 Stage 和 Job，GitLab 按剧本演。文件放在项目根目录，格式是 YAML，缩进两个空格，不支持 tab。

我见过不少人上来就写错缩进，结果流水线直接报语法错。后来我养成了一个习惯：先在 GitLab CI Lint 页面里校验一下，省得浪费时间。

# 一个最简单的 Android 流水线
stages:
  - build
  - test
  - deploy

before_script:
  - echo "开始执行 CI"

build_job:
  stage: build
  script:
    - ./gradlew assembleDebug
  artifacts:
    paths:
      - app/build/outputs/apk/debug/

test_job:
  stage: test
  script:
    - ./gradlew testDebugUnitTest

deploy_job:
  stage: deploy
  script:
    - echo "部署到测试环境"
  only:
    - master

上面这个例子包含了几个核心关键字：stages 定义阶段顺序，before_script 是每个 Job 执行前跑的通用脚本，artifacts 保存构建产物，only 控制触发分支。嗯，这些参数后面我们会一个一个细讲。

Job 与 Stage：组织你的流水线

Stage 是阶段，Job 是任务。一个 Stage 里可以跑多个 Job，这些 Job 是并行执行的。不同 Stage 则是串行的——前一个 Stage 全部成功了，下一个才会开始。你想想看，这刚好符合 Android 构建的典型流程：先编译，再测试，最后部署，互不干扰。

我记得有一次团队里有人把单元测试和 UI 测试放到了同一个 Stage，结果 UI 测试跑了 20 分钟，单元测试早跑完了但还得等。我建议拆成两个 Stage，利用并行提速，效果很明显。

关键字	作用	示例
`stages`	定义所有 Stage 及其顺序	`stages: [build, test]`
`stage`	指定 Job 所属 Stage	`stage: build`
`script`	Job 要执行的命令	`script: ["./gradlew assemble"]`
`artifacts`	保存的产物（可下载）	`artifacts: {paths: [...]}`
`only / except`	限制 Job 触发的分支/条件	`only: [master]`
`tags`	指定 Runner 的标签	`tags: [android]`

💡 避坑指南： 如果你写了一个 Job 但没指定 stage，它会默认归属到 test 阶段。我曾经踩过这个坑——本来想放 build 里的编译任务被丢到了 test 阶段，导致流水线一直报错找不到产物。记住，显式写 stage: 总是更安全。

Runner 配置：让任务跑起来

光有 YAML 文件还不够，你需要一个 Runner 来实际执行。Runner 可以装在你的开发机上、服务器上，或者用 GitLab 官方的共享 Runner。我个人建议团队用自己注册的专用 Runner，因为共享 Runner 的磁盘和网络环境不稳定，尤其是 Android 构建需要下载 Gradle 和 SDK，容易超时。

注册一个 Runner 很简单，几步搞定：

在项目 → Settings → CI/CD → Runners 页面找到注册。
在 Runner 所在机器上运行 gitlab-runner register，按提示输入 URL 和。
选择执行器（executor），Android 构建推荐用 docker 或 shell。我习惯用 docker，隔离性好，配个带 Android SDK 的镜像就行。
给 Runner 打标签（比如 android、linux），这样在 YAML 里用 tags 指定，就能精准命中。

# 注册 Runner 的交互示例
$ gitlab-runner register
请输⼊ GitLab 实例 URL: https://gitlab.com/
请输⼊注册 : xxxxxxxxxxx
请输⼊ Runner 描述: android-build-runner
请输⼊ Runner 标签: android,linux
请输⼊执行器: docker
默认镜像: android-sdk:latest

⚠️ 注意： 记得给 Runner 打标签，并且在 Job 里写上对应的 tags。如果不写 tags，Job 会去找所有不带标签的 Runner。我遇到过很多次 Job 一直处于 pending 状态，就是因为标签没对上。排查方法：去 Runner 页面看在线状态和匹配的 Job 列表。

一点点个人感悟

刚开始配置 GitLab CI/CD 时，我经常在 YAML 语法上翻车。后来我总结了一个方法：先写一个最简单的单 Stage 单 Job，跑通后再逐步加复杂逻辑。另外，.gitlab-ci.yml 里不要塞太多 script，尽量拆成独立的脚本文件，放到项目里，CI 里直接调用，这样测试和调试都方便。