08. .gitlab-ci.yml 怎么写?从 Hello World 到生产配置

「GitLab」系列已发布: 00. GitLab 不只是代码托管:一套 DevOps 平台的 6 大核心能力 | 01. GitLab 怎么装最省心?Omnibus/Docker/K8s 三种姿势 | 02. 装完 GitLab 先配啥?管理员视角的初始化设置清单 | 03. GitLab 角色搞不清?Member/Maintainer/Owner 权限全解 | 04. 从零建好第一个 GitLab 项目:权限、变量、CI 配置入门 | 05. GitLab MR 代码审查:Code Review 最佳实践 | 06. CI/CD 到底是什么?GitLab 流水线架构从概念到实战 | 07. Runner 装不好?GitLab Runner 单机/分布式/高可用全攻略 | 08. .gitlab-ci.yml 怎么写?从 Hello World 到生产配置(本文) | 09. 从 0 到 1:Go + React 项目的 GitLab CI/CD 实战部署

一个 yml 文件定义整条流水线。从最简单的 Hello World 到 stages、变量、缓存、制品的生产级配置,语法全解析带你上手。

前置条件

已完成 Runner 安装与注册(第 07 篇),理解 CI/CD 基本概念(第 06 篇)。需要一个注册了 Runner 的项目来测试配置。

一、.gitlab-ci.yml 概述

放在项目根目录的 YAML 文件。GitLab 检测到推送时读取它,决定怎么跑 CI/CD Pipeline。


# 必须包含 stages 指令(除非用 rules 不用 stages)
stages:
  - build
  - test
  - deploy

二、基础指令

2.1 script

Job 执行的命令:

build:
  stage: build
  script:
    - echo "Building..."
    - npm install
    - npm run build

2.2 image

指定 Docker 镜像:

build:
  image: node:18-alpine
  script:
    - npm install
    - npm run build

2.3 before_script / after_script

before_script:
  - echo "准备环境..."
  - npm ci

after_script:
  - echo "清理临时文件"
  - rm -rf node_modules

2.4 artifacts

保留 Job 输出文件:

build:
  artifacts:
    paths:
      - dist/
      - build/
    expire_in: 1 week

2.5 cache

缓存依赖加速构建:

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/
    - .cache/

三、控制指令

3.1 only / except

deploy:
  script:
    - echo "Deploying..."
  only:
    - main
    - tags

3.2 rules (推荐)

deploy:
  script:
    - echo "Deploying..."
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
    - if: $CI_COMMIT_TAG
      when: always
    - when: never

3.3 needs

控制 Job 依赖关系:

test:
  needs: []        # 不等待任何 Job
  script:
    - echo "Testing..."

deploy:
  needs: [test]    # 等待 test 完成
  script:
    - echo "Deploying..."

3.4 parallel

并行执行多个 Job:

test:
  parallel: 3
  script:
    - echo "Running test $CI_NODE_INDEX of $CI_NODE_TOTAL"

四、变量管理

4.1 项目变量

Settings → CI/CD → Variables:

  • 普通变量
  • 保护变量(仅保护分支)
  • 加密变量(加密存储)

4.2 文件变量

variables:
  DB_HOST: "localhost"
  API_URL: "https://api.example.com"

4.3 预设变量

变量 说明
CI_COMMIT_SHA 提交 SHA
CI_COMMIT_REF_NAME 分支/标签名
CI_PROJECT_NAME 项目名称
CI_JOB_NAME Job 名称
CI_PIPELINE_ID Pipeline ID

五、模板与继承

5.1 extends

.base:
  image: node:18-alpine
  before_script:
    - npm ci

build:
  extends: .base
  stage: build
  script:
    - npm run build

test:
  extends: .base
  stage: test
  script:
    - npm test

5.2 内建模板

GitLab 提供 include 指令引入模板:

include:
  - template: Security/Secret-Detection.gitlab-ci.yml
  - local: '.gitlab-ci/templates/build.yml'

六、常用配置示例

6.1 Node.js 项目

stages:
  - install
  - build
  - test
  - deploy

install:
  image: node:18-alpine
  stage: install
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
  script:
    - npm ci

build:
  image: node:18-alpine
  stage: build
  needs: [install]
  script:
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

test:
  image: node:18-alpine
  stage: test
  needs: [install]
  script:
    - npm test
  artifacts:
    when: on_failure
    paths:
      - coverage/

deploy:
  image: alpine:latest
  stage: deploy
  needs: [build, test]
  script:
    - echo "Deploying to production"
  only:
    - main

6.2 Python 项目

stages:
  - lint
  - test
  - deploy

lint:
  image: python:3.11
  script:
    - pip install flake8
    - flake8 .

test:
  image: python:3.11
  script:
    - pip install -r requirements.txt
    - pytest
  artifacts:
    when: on_failure
    paths:
      - tests/reports/

deploy:
  image: alpine:latest
  script:
    - echo "Deploying Python app"
  only:
    - main

6.3 Go 项目

stages:
  - build
  - test
  - release

build:
  image: golang:1.21
  script:
    - go build -o bin/app ./cmd/server
  artifacts:
    paths:
      - bin/

test:
  image: golang:1.21
  script:
    - go test -v ./...
  artifacts:
    when: on_failure
    paths:
      - coverage.out

release:
  image: alpine:latest
  script:
    - apk add git
    - git tag v$CI_COMMIT_SHORT_SHA
    - git push origin v$CI_COMMIT_SHORT_SHA
  only:
    - main

七、文章引用

📌 本文首发于微信公众号 【运维知识点滴】——专注运维实战干货,微信搜索“运维知识点滴”或扫下方二维码关注,更新不迷路。

微信公众号【运维知识点滴】 微信小程序【A5单据合并&大试卷拆分转A4打印】
运维实战干货 · 关注追更 Word 转 PDF · 试卷/发票打印神器 · 免费
运维实战干货 · 关注追更 Word 转 PDF · 试卷/发票打印神器 · 免费

💡 小程序【A5单据合并&大试卷拆分转A4打印】是干嘛的? 一个 Word 转 PDF 的打印神器,专治“文档版式和打印机对不上”:

  • A3 试卷打不出来? 学校发的电子版试卷多是 A3,家用打印机只吃 A4——上传 Word 一键转换:可缩到一页 A4(页数不变),也可对半拆成两张 A4(1:1 原大、字更清晰),两种模式自选;
  • 版式不乱:真实渲染引擎原样转换、绝不重排内容,转出的 PDF 和原 Word 排版一致,公式/表格/图片不跑版;
  • 两张 A5 单据拼一张 A4:出租车票、火车票等报销凭证拼版后,一次打印、整齐粘贴;
  • 隐私省心:无需注册,转换结果留存 5 天、最多下载 5 次即自动删除,不留任何历史记录;
  • 微信扫码即用,免费、免安装,支持 doc / docx(≤50MB)。

上一篇:07. Runner 装不好?GitLab Runner 单机/分布式/高可用全攻略 | 下一篇:09. 从 0 到 1:Go + React 项目的 GitLab CI/CD 实战部署