.gitlab-ci.yml 简介

variables:
  GIT_STRATEGY: fetch
  GIT_DEPTH: "1" # 只下载最近的一次 commit，不下载历史记录，速度极快


## 深度解析：复杂流程完整实例

**场景假设**：
我们要构建一个 Node.js 应用。

1.  **全局配置**：默认使用 Node 镜像，设置重试机制。
2.  **Lint 阶段**：代码风格检查，允许失败（不阻塞流程）。
3.  **Build 阶段**：编译代码，生成 `dist/` 目录作为产物。
4.  **Test 阶段**：
    - 单元测试：需要 `dist/` 文件。
    - 安全扫描：使用特定 Docker 镜像，耗时较长。
5.  **Deploy 阶段**：
    - **Staging**：当合并到 `main` 分支时自动部署。
    - **Production**：只有打 `v*` 格式的 Tag 时才部署，且需要人工点击确认。

### 完整的 `.gitlab-ci.yml` 内容

```yaml
# 1. 定义整个流水线的阶段顺序
stages:
  - check # 代码检查
  - build # 构建
  - test # 测试
  - deploy # 部署

# 2. 全局默认配置 (Default)
# 所有 Job 如果没有单独指定，都会继承这里的配置
default:
  image: node:16-alpine # 默认使用 Node 16 镜像
  retry: 1 # 如果 Job 失败，自动重试 1 次
  tags: # 指定默认由带 'docker' 标签的 Runner 执行
    - docker

# 全局变量
variables:
  NPM_CONFIG_CACHE: '$CI_PROJECT_DIR/.npm'

# 3. 缓存配置：在 Job 之间共享 node_modules，加快速度
cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/
    - .npm/

# 4. 模版作业 (Hidden Job / Template)
# 以 '.' 开头，不会直接运行，专门用于被 extends 继承
.deploy_template:
  stage: deploy
  script:
    - echo "Deploying to $DEPLOY_ENV..."
    - echo "Simulate deployment script here"
    # 假设这里有真实部署命令，如 scp 或 kubectl
  dependencies:
    - build_app # 明确只下载 build_app 的产物

# =======================
# Stage: CHECK
# =======================
lint_code:
  stage: check
  script:
    - npm ci
    - npm run lint
  # 关键字: allow_failure
  # 即使代码风格检查失败，流水线也会显示橙色警告，但继续执行后续 Build
  allow_failure: true

# =======================
# Stage: BUILD
# =======================
build_app:
  stage: build
  script:
    - npm ci
    - npm run build
  # 关键字: artifacts
  # 定义产物，build 完成后，GitLab 会把 dist 目录压缩保存
  artifacts:
    name: 'dist-$CI_COMMIT_REF_NAME'
    expire_in: 1 week # 产物保留1周
    paths:
      - dist/ # 指定要保留的文件夹

# =======================
# Stage: TEST
# =======================
unit_test:
  stage: test
  script:
    - npm run test
  # 关键字: dependencies
  # 显式声明依赖 build_app，GitLab 会自动把 build_app 的 artifacts 下载并解压到当前目录
  dependencies:
    - build_app

security_scan:
  stage: test
  # 关键字: image (覆盖全局 default)
  # 这个 Job 需要特殊的安全工具镜像，不使用默认的 Node 镜像
  image: aquasec/trivy:latest
  script:
    - trivy filesystem .
  # 关键字: rules (逻辑控制)
  # 仅在 main 分支 或 Tag 时运行，Merge Request 中不运行以节省资源
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
    - if: $CI_COMMIT_TAG

# =======================
# Stage: DEPLOY
# =======================

# 部署到测试环境
deploy_staging:
  # 关键字: extends
  # 继承上面定义的 .deploy_template，复用 script 和 dependencies
  extends: .deploy_template
  variables:
    DEPLOY_ENV: 'Staging'
  environment:
    name: staging
    url: https://staging.example.com
  # 规则：只有当推送到 main 分支时执行
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

# 部署到生产环境
deploy_production:
  extends: .deploy_template
  variables:
    DEPLOY_ENV: 'Production'
  environment:
    name: production
    url: https://example.com
  # 规则：只有打 Tag (例如 v1.0.0) 时才执行
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
      when: manual # 关键：手动触发。流水线会暂停，等待人工点击`播放`按钮
  # 生产环境通常不允许失败
  allow_failure: false

stages:
  - check
  - build
  - test
  - deploy

.deploy_template:
  script: ...

deploy_staging:
  extends: .deploy_template

rules:
  - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
    when: manual

spec:
  inputs:
    image_version:
      default: 'latest'
---
# 这是一个【隐藏 Job】，它以 . 开头。GitLab 不会单独运行它。
.go_base_setup:
  image: golang:$[[ inputs.image_version ]]
  before_script:
    - echo "Setting up Go environment..."
    - go mod download

# 这是一个【真正的 Job】。用户引入组件后，实际运行的是这个。
build_api:
  extends: .go_base_setup # 继承上面隐藏 Job 的所有配置
  stage: build
  script:
    - go build -o api_server ./cmd/api

# 这是另一个【真正的 Job】，它复用了相同的环境配置
build_worker:
  extends: .go_base_setup # 再次继承
  stage: build
  script:
    - go build -o worker ./cmd/worker

my-catalog-project/
├── templates/
│   ├── .internal-scripts.yml   # 以 . 开头，对外隐藏（私有辅助文件）
│   └── deploy.yml              # 正常的组件，对外暴露（公共组件）

# deploy.yml
spec:
  inputs:
    env:
      default: 'prod'
---
# 引入同目录下的隐藏文件
include:
  - local: '/templates/.internal-scripts.yml'

deploy_job:
  stage: deploy
  script:
    - !reference [.deploy_scripts, run] # 调用隐藏文件里的逻辑

test_job:
  stage: test
  script:
    - echo "运行测试脚本..."
    - exit 1 # 模拟脚本执行失败
  after_script:
    - echo "当前 Job 的状态是 $CI_JOB_STATUS"
    - >
      if [ "$CI_JOB_STATUS" = "failed" ]; then
        echo "检测到 Job 失败！开始执行失败后的补救/通知动作..."
      elif [ "$CI_JOB_STATUS" = "success" ]; then
        echo "Job 执行成功，执行成功后的动作..."
      else
        echo "Job 状态为 $CI_JOB_STATUS"
      fi