GitLab CI/CD学习教程（第四章gitlab-ci.yml）

GitLab CI/CD学习教程（第四章gitlab-ci.yml）

🚀从零开始，结合具体场景和示例，让你彻底掌握 GitLab CI/CD 的配置！

1 定义

⭐ 什么是.gitlab-ci.yml

在上一章节中，我们详细讲述了Pipeline的定义，本章节将重点讲解如何对Pipeline进行精细化的控制。

.gitlab-ci.yml 文件是 GitLab CI/CD 管道的配置文件。它以 YAML 格式定义了流水线（Pipeline）的各个阶段（stages）和任务（jobs）。每当你向 GitLab 仓库提交代码时，GitLab 会根据 .gitlab-ci.yml 文件自动执行预定的任务。

2 基础语法

.gitlab-ci.yml 配置文件使用的是 YAML语法，规则十分简单，是一种简洁的数据序列化语言，主要特点是可读性强，并且支持层级结构。

• 🧤 缩进

  用空格（不能用 Tab），通常用 2 个空格缩进。

• 🎎 键值对

  配置项是由键key和值value组成的。例如：stages: [build, test, deploy]

• 📊 列表

  用 - 表示列表项

• ⚙ 多行脚本

  用 | 或 >（保留换行/折叠换行）

• 💬 注释

  以 # 开头的行表示注释，GitLab CI/CD 会忽略这些行。

3 关键配置项

这里需要对only和when区别作一个详细的解释。(PS: 建议使用rules，它更强大和灵活)

• 意图：only 更侧重于指定作业应该在哪种类型的变更（如特定分支或标签）上运行；而 when 则关注于作业在整个管道流程中的执行策略。
• 灵活性：虽然两者都能影响作业是否执行，但是 when 提供了关于作业执行时机的更多选项，并且可以结合其他条件（例如通过 rules）来实现更为复杂的逻辑。

4 预定义变量

📙 官方文档

预定义变量在流水线执行的三个不同阶段可用：

• 预流水线：预流水线变量在创建流水线之前可用。这些变量是仅使用 include:rules 来控制在创建流水线时要使用哪些配置文件。
• 流水线：这些变量在流水线创建时可用。除了预流水线变量外，流水线- 变量还可以用于配置在作业中定义的 rules ，以确定要添加到流水线中的哪些作业。
• 仅作业：这些变量仅在 runner 选择作业并运行作业时为每个作业可用。

常用的预定义变量: (更多其他变量请查阅官方文档)

5 简单示例

5.1 Vue.js 项目

image: node:18

stages:
  - install
  - build
  - deploy

cache:
  key: $CI_COMMIT_REF_SLUG
  paths:
    - node_modules/

install-deps:
  stage: install
  script:
    - npm ci
  only:
    - main

build-prod:
  stage: build
  script:
    - npm run build
  artifacts:
    paths:
      - dist/

deploy-s3:
  stage: deploy
  image: amazon/aws-cli:latest
  script:
    - aws s3 sync dist/ s3://my-bucket/ --delete
  only:
    - main

5.2 Python Django 项目

image: python:3.10

stages:
  - test

services:
  - postgres:13

variables:
  POSTGRES_DB: mydb
  POSTGRES_USER: runner
  POSTGRES_PASSWORD: ""
  DATABASE_URL: "postgres://runner:@postgres:5432/mydb"

test:
  stage: test
  before_script:
    - pip install -r requirements.txt
    - python manage.py migrate
  script:
    - pytest --cov=.
  coverage: '/^TOTAL.+?(\d+\%)$/'

5.3 Qt/C++ 项目（Windows + shell环境）

# 包含共享配置
include:
  - local: '/.ci-templates/variables.yml'  # 共享变量定义

# 定义工作流规则
workflow:
  rules:
    - if: '$CI_COMMIT_TAG'                 # 标签提交触发完整流水线
      variables:
        DEPLOY_ENV: "production"
    - if: '$CI_COMMIT_BRANCH == "main"'    # main分支触发构建、测试、打包
      variables:
        DEPLOY_ENV: "staging"
    - when: manual                         # 允许手动触发

# 全局配置
variables:
  QT_ROOT: "C:\\Qt"
  QIFW_BIN: "C:\\Qt\\Tools\\QtInstallerFramework\\4.6\\bin"
  BUILD_SCRIPT: "scripts/build.py"
  PACKAGE_SCRIPT: "scripts/package.py"
  RELEASE_SCRIPT: "scripts/release.py"

# 阶段定义
stages:
  - prepare
  - build
  - test
  - package
  - release

# 公共before_script
before_script:
  - echo "Running on $CI_RUNNER_DESCRIPTION"
  - python --version
  - pip install -r requirements-ci.txt
  - export ARTIFACTS_DIR="$CI_PROJECT_DIR/artifacts"
  - mkdir -p $ARTIFACTS_DIR

# 公共after_script
after_script:
  - echo "Cleaning temporary files..."
  - rm -rf tmp_build

# 准备阶段
prepare-env:
  stage: prepare
  rules:
    - if: '$DEPLOY_ENV == "production" || $DEPLOY_ENV == "staging"'
  script:
    - python $BUILD_SCRIPT prepare
      --qt-version 5.15.2
      --platform win64
      --output-dir $ARTIFACTS_DIR
  artifacts:
    paths:
      - $ARTIFACTS_DIR/qt_env.bat
    expire_in: 1h

# 并行构建任务
build-windows:
  stage: build
  needs: ["prepare-env"]  # 显式声明依赖
  parallel: 2  # 并行构建两个配置
  rules:
    - if: '$DEPLOY_ENV == "production"'
      variables:
        BUILD_TYPE: "release"
    - if: '$DEPLOY_ENV == "staging"'
      variables:
        BUILD_TYPE: "debug"
  script:
    - call $ARTIFACTS_DIR/qt_env.bat
    - python $BUILD_SCRIPT compile
      --type $BUILD_TYPE
      --jobs 4
      --output $ARTIFACTS_DIR/$BUILD_TYPE
  artifacts:
    paths:
      - $ARTIFACTS_DIR/$BUILD_TYPE/**
    reports:
      dotenv: $ARTIFACTS_DIR/build_info.env

# 测试阶段
run-tests:
  stage: test
  needs:
    - job: build-windows
      artifacts: true
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  script:
    - python -m pytest tests/ -v --junitxml=test-results.xml
    - python $BUILD_SCRIPT analyze-coverage
      --input build/coverage
      --output $ARTIFACTS_DIR/coverage_report.html
  artifacts:
    paths:
      - test-results.xml
      - $ARTIFACTS_DIR/coverage_report.html
    reports:
      junit: test-results.xml

# 打包阶段
create-installer:
  stage: package
  needs:
    - build-windows
    - run-tests
  rules:
    - if: '$DEPLOY_ENV == "production"'
  script:
    - python $PACKAGE_SCRIPT
      --config installer/windows/config.xml
      --source $ARTIFACTS_DIR/release
      --output $ARTIFACTS_DIR/installer
      --tool-path $QIFW_BIN
  artifacts:
    paths:
      - $ARTIFACTS_DIR/installer/*.exe
    expire_in: 1 week

# 发布阶段
deploy-release:
  stage: release
  needs: ["create-installer"]
  rules:
    - if: '$CI_COMMIT_TAG != null'
  script:
    - python $RELEASE_SCRIPT
      --tag $CI_COMMIT_TAG
      --artifact $ARTIFACTS_DIR/installer/*.exe
      --changelog changelog.md
  environment:
    name: production
    url: https://downloads.example.com

# 安全扫描（动态包含）
include:
  - template: Security/SAST.gitlab-ci.yml

上一篇：《GitLab CI/CD学习教程 第三章Pipeline》
下一篇：《GitLab CI/CD学习教程 第五章高级示例》正在编写中…