HelloWorld 与 GitLab CI 配合教程

本教程手把手教你如何把一个简单的 HelloWorld 项目接入 GitLab CI：从仓库和 .gitlab-ci.yml 的最小示例开始，讲清 Runner、镜像、变量、缓存与 artifacts 的用法，并给出 Node/Python/Go 等语言的实操配置与常见排错建议，能让你在本地或云端快速复现并扩展到真实项目。

HelloWorld 与 GitLab CI 配合教程

先说为什么要这么做

把 HelloWorld 拿来做 CI，一点都不无聊，反而是理解整个持续集成流程最清晰的方式。你可以把复杂概念拆成小块：构建、测试、打包、部署。用最简单的输出“Hello World”去验证每一步是否连通，比直接在大型项目上调试要省时省力得多。

关键概念快速扫一遍

  • Pipeline：由若干 stage（阶段）组成的执行序列。
  • Stage：例如 build、test、deploy，按顺序执行。
  • Job：Stage 中的单元，实际执行脚本。
  • Runner：执行 Job 的工作者，可以是共享的也可以是自建的。
  • .gitlab-ci.yml：放在仓库根目录的配置文件，定义 pipeline 行为。

准备工作（先决条件）

  • 一个 GitLab 仓库（可用 GitLab.com 免费仓库或自建 GitLab）。
  • 有权限编辑仓库并推送代码。
  • （可选）如果使用自建 Runner，需要一台能安装 Runner 的主机。
  • 本地已安装 Git，用于 push 流程验证。

最小可运行示例：从 HelloWorld 开始

先看一个最简单的 .gitlab-ci.yml，能让你立即看到 Pipeline 执行。

stages:
  - build
  - test

hello_build:
  stage: build
  script:
    - echo "Building HelloWorld..."
  tags: []

hello_test:
  stage: test
  script:
    - echo "Hello, World!" > output.txt
    - cat output.txt
  artifacts:
    paths:
      - output.txt
    expire_in: 1 hour

解释一下：

  • stages：定义了两个阶段，先 build 再 test。
  • hello_build 和 hello_test：两个 job 的名字，分别属于不同阶段。
  • script：job 中要执行的 shell 命令。
  • artifacts：保存 job 输出，方便在 Web UI 下载或后续 job 使用。

如何运行它（步骤）

  • 在仓库根目录创建 .gitlab-ci.yml，粘贴上面的内容。
  • git add、commit、push 到 GitLab。
  • 在 GitLab 的项目页面 -> CI/CD -> Pipelines 中可以看到新 Pipeline 被触发。

用 Docker 镜像执行 Job

GitLab CI 很常见的做法是直接在 job 里指定镜像，这样环境可控、可复现。举个 Node.js HelloWorld 的例子：

image: node:16

stages:
  - test

npm_test:
  stage: test
  script:
    - node -v
    - echo "console.log('hello')" > index.js
    - node index.js

把 image 放在顶层表示默认镜像，job 里可以覆盖。这样你不用在 Runner 上事先安装语言环境。

多语言示例快速参考

下面是几个常见语言的 minimal pipeline，便于照搬到你的项目中。

  • Python 
    image: python:3.10
stages: [test]
pytest_job:
  script:
    - python -V
    - echo "print('hello')" > hello.py
    - python hello.py
  • Go 
    image: golang:1.20
stages: [build]
build:
  script:
    - echo 'package main; import "fmt"; func main(){fmt.Println("hello")}' > main.go
    - go build -o hello main.go
    - ./hello
  • Java（Maven） 
    image: maven:3.8-jdk-11
stages: [build]
maven_build:
  script:
    - mvn -version
    - echo "tiny placeholder" > README.md

Runner：哪里在跑这些命令？

GitLab Runner 是实际执行脚本的进程，有几种常见类型：

  • Shared Runner：GitLab.com 提供的公共 Runner，开启快速上手。
  • Specific Runner：指定在某个项目或组使用，适合私有资源或需要特殊权限的场景。
  • Executors：Runner 的执行模式，例如 docker、shell、docker-machine 等。

常用组合是自建 Runner + docker executor。注册 Runner 的基本流程是：

  • 在机器上安装 GitLab Runner。
  • 执行 gitlab-runner register，填入 GitLab 给的 URL 和 token，选择 executor（如 docker）。
  • 配置 tags，以便在 .gitlab-ci.yml 中通过 tags 精确匹配 Runner。

变量、缓存与 artifacts 的差别（很容易搞混）

顺序记住这三者的职责会省很多麻烦：

  • 变量（CI/CD variables）：用于在 pipeline 中传递配置信息或密钥（可设为保护/Masked）。
  • 缓存（cache）：用于保存依赖以加速后续 job（例如 node_modules），更偏向速度优化，不保证每次都存在。
  • 工件（artifacts）：明确保存为后续 job 或下载用的产物，通常用于测试报告、构建产物。
用途 持续性 示例
变量 配置级别 API_KEY、ENV
缓存 可失效（速度优化） node_modules、.cache
artifacts 明确保留（下载/传递） 构建产物、测试报告

实用场景与进阶配置

  • 并行 Job：用 needs/parallel，可以缩短流水线执行时间。
  • 只有在特定分支或 tag 才执行的 Job：使用 only/except 或 rules。
  • 手动触发与保护分支部署：把部署设为 manual 并只允许 protected branches。
  • 定时任务：在 GitLab UI 里配置 Scheduled Pipelines，用于定期构建或健康检查。

rules vs only/except（现代推荐 rules）

rules 更灵活，能根据变量、文件变化、管道来源来决定是否执行，比只用 branch name 更强。

常见问题与排错思路（实战经验）

  • Job 一直 pending：通常是没有匹配的 Runner，检查 tags、Runner 是否 online。
  • 镜像拉取失败：网络或私有仓库鉴权问题，试着在本地 docker pull 同镜像看报错。
  • 权限不足（写文件、访问 docker）：如果用 shell executor，Runner 的用户权限要确认；用 docker executor 时注意 volumes 的权限。
  • 缓存未命中：检查 cache:key 是否合理，路径是否指向正确目录。
  • 变量没生效：确认变量是否设置在项目或 group 级别，是否被保护/Masked 导致不可见。

一个更完整的示例：构建、测试、发布到临时环境

image: node:16

stages:
  - build
  - test
  - deploy

variables:
  APP_ENV: "staging"

cache:
  paths:
    - node_modules/

install:
  stage: build
  script:
    - npm ci
  artifacts:
    paths:
      - node_modules/

unit_tests:
  stage: test
  script:
    - npm run test
  dependencies:
    - install
  artifacts:
    when: always
    reports:
      junit: test-results/*.xml

deploy_staging:
  stage: deploy
  script:
    - echo "Deploying to $APP_ENV"
    - ./scripts/deploy.sh $APP_ENV
  when: manual
  environment:
    name: staging
    url: https://staging.example.com

这段配置展示了 artifacts、dependencies、environment 的组合用法。手动部署（when: manual）适合你想在通过测试后有人批准再发布的场景。

安全性与最佳实践（别忽视）

  • 把敏感信息放到 GitLab CI/CD 的 Variables 中并设为 Masked/Protected。
  • 尽量使用官方或可信镜像，避免在镜像里包含秘密。
  • 使用 Specific Runner 时尽量给 Runner 最小权限，避免泄露宿主机能力。
  • 合理设置 artifacts 的过期时间，避免占用大量存储。

小技巧与性能优化

  • 用 cache 缓存依赖，加速后续 pipeline；注意 cache key 控制更新策略。
  • 把长时间运行但不常改动的步骤拆成独立 job，减少重复执行。
  • 多用并行 jobs（并行测试分片）缩短总体时间。
  • 在 Pipeline 中输出必要的调试信息（node -v、env），方便排查环境差异。

我遇到的几个容易忽视的小坑

  • Windows 路径和换行：如果你的 Runner 是 Windows，脚本的换行和路径要注意。
  • 镜像大小：大镜像启动慢，选轻量级镜像可以显著提升体验。
  • Artifacts 依赖关系：如果没写 dependencies，后续 job 可能拿不到想要的 artifacts。

参考模型：把 HelloWorld 扩展到真实项目的路线图

  • 阶段 1：把项目能在 CI 上跑通（构建 + 单元测试）。
  • 阶段 2：加入缓存、并行、提升速度，减少每次流水线时间。
  • 阶段 3：增加集成测试、环境（staging）部署、手动审批。
  • 阶段 4：自动化生产部署、告警与回滚策略。

好啦，就先写到这儿——如果你跟着例子一步步做，会发现 HelloWorld 足够把概念和常见坑都覆盖到位。动手是最好的老师，碰到具体出错信息再对着日志一步步查就行，基本流程与关键点都在上面了，接下来就看你想往哪个方向扩展了。

返回首页