gitlab的ci配置文件yaml参数说明

GitLab CI配置文件YAML参数说明

一、什么是 .gitlab-ci.yml？

.gitlab-ci.yml 是GitLab CI/CD的核心配置文件，用于定义流水线中的作业（Job）和执行阶段（Stage）。通过它，您可以实现从代码提交到构建、测试、部署的全自动化流程。

二、全局参数（控制流水线行为）

这些参数位于文件顶层，影响整个流水线。

参数	说明	示例
stages	定义作业执行阶段的顺序	stages: [build, test, deploy]
variables	设置所有作业通用的变量	variables: { DEPLOY_ENV: "prod" }
default	为所有作业设置默认值（如image、before_script）	default: { image: ruby:3.0, retry: 2 }
workflow	控制流水线是否运行及运行规则	workflow: { rules: [ { if: "$CI_COMMIT_BRANCH == 'main'" } ] }
include	引入外部CI/CD配置文件（本地、项目、远程、模板）	include: { local: '/templates/build.yml' }

重点：workflow 高级用法

• workflow:name：动态命名流水线

  workflow:
    name: 'Pipeline for $CI_COMMIT_BRANCH'

• workflow:rules：按条件决定是否创建流水线

  workflow:
    rules:
      - if: $CI_MERGE_REQUEST_ID
        when: never
      - when: always

• 自动取消冗余流水线

  workflow:
    auto_cancel:
      on_new_commit: interruptible   # 只取消可中断作业
      on_job_failure: all            # 任一作业失败即取消所有运行中作业

三、作业参数（定义单个作业行为）

每个作业至少需要 script 参数，并可按需组合以下参数。

参数	说明	常用值 / 示例
script	在Runner中执行的Shell命令（必需）	script: ["bundle exec rspec"]
before_script	作业执行前运行的命令	before_script: ["bundle install"]
after_script	作业执行后（包括失败时）运行的命令	after_script: ["cleanup.sh"]
stage	指定作业所属阶段（默认test）	stage: build
image	使用的Docker镜像	image: node:18-alpine
tags	选择带有特定标签的Runner	tags: [docker, aws]
allow_failure	允许作业失败而不阻塞后续阶段	allow_failure: true
when	执行条件：on_success、manual、always等	when: manual
retry	失败时自动重试次数	retry: 2
timeout	作业超时时间（覆盖项目设置）	timeout: 30 minutes
parallel	并行执行作业实例数量	parallel: 5
interruptible	新提交时是否可取消当前作业	interruptible: true
needs	跳过阶段顺序，直接依赖其他作业	needs: [build_job]
dependencies	限制获取哪些上游作业的产物	dependencies: [build_job]
environment	关联部署环境	environment: staging
coverage	从日志提取覆盖率的正则表达式	coverage: '/Coverage: \d+\.\d+%/'

四、产物与缓存（加速流水线）

1. artifacts ------ 作业成功后保存的文件

job:
  artifacts:
    paths:                # 必须：要保存的文件路径
      - binaries/
      - .config
    exclude:              # 排除特定文件
      - binaries/**/*.o
    expire_in: "1 week"   # 过期时间（默认30天）
    expose_as: "测试报告"  # MR界面显示名称
    when: on_failure      # 何时上传（默认on_success）

2. cache ------ 跨作业缓存依赖

job:
  cache:
    key: "$CI_JOB_NAME"   # 缓存标识（支持变量）
    paths:
      - node_modules/
    untracked: true       # 包含所有未跟踪文件
    policy: pull-push     # pull-only 只拉取不推送

高级缓存键：

• key:files ------ 根据文件内容生成键（如Gemfile.lock的SHA）
• key:prefix ------ 为files键添加前缀

五、条件执行（rules 与 only/except）

GitLab推荐使用rules替代旧式的only/except。

job:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: manual
      allow_failure: true
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
      when: on_success
      variables:                     # 为匹配的规则设置变量
        DEPLOY_VARIANT: "production"
    - when: never                    # 不满足以上规则时跳过

六、包含外部配置（include）

使用include复用配置，避免重复。

类型	语法	场景
本地文件	include: local: '/.ci/build.yml'	同仓库文件
项目文件	include: { project: 'group/proj', file: 'config.yml' }	跨项目共用
远程URL	include: remote: 'https://example.com/template.yml'	外网模板
官方模板	include: template: Auto-DevOps.gitlab-ci.yml	快速集成

条件包含及缓存

include:
  - local: 'security.yml'
    rules:
      - if: '$CI_COMMIT_BRANCH == "main"'   # 只在主分支包含
    cache: '1 hour'                          # 缓存远程文件1小时

七、输入参数（spec:inputs）

允许配置模板化，让使用方动态传入值。

spec:
  inputs:
    environment:
      default: staging
      description: "部署环境"
      type: string
      options: [dev, staging, prod]
    version:
      regex: '^v\d+\.\d+$'   # 正则验证

job:
  script: echo "部署到 $[[ inputs.environment ]]"

使用时通过include传入参数：

include:
  - local: 'deployment.yml'
    inputs:
      environment: prod

八、常见模式与最佳实践

1. 多阶段流水线模板

stages: [build, test, deploy]

variables:
  DOCKER_REGISTRY: registry.example.com

default:
  image: node:18
  before_script:
    - npm ci

build-job:
  stage: build
  script: npm run build
  artifacts:
    paths: [dist/]

test-job:
  stage: test
  script: npm test

deploy-prod:
  stage: deploy
  script: deploy.sh
  environment: production
  when: manual
  only: [main]

2. 使用needs优化并行

build: { stage: build, script: make }
test:
  stage: test
  script: make test
  needs: [build]          # 不等同阶段作业，直接开始

3. 动态调整行为

job:
  script:
    - if [ "$VERSION" == "latest" ]; then deploy.sh; fi
  variables:
    VERSION: $([[ "$CI_COMMIT_TAG" =~ ^v.*$ ]] && echo "latest" || echo "stable")

九、验证与调试

• 在线语法校验 ：访问项目的 CI/CD → Pipelines → CI Lint，粘贴配置检查错误
• 本地验证 （需安装gitlab-ci-local工具）：gitlab-ci-local --dry-run
• 查看扩展后的配置 ：通过API获取解析后的完整YAML：
  GET /projects/:id/ci/lint

十、常见问题排查

问题现象	可能原因	解决方案
流水线未触发	workflow:rules全部为never	检查规则，确保至少一条when: always
缓存不生效	cache:key在不同作业中不匹配	统一缓存键或使用files派生键
产物下载失败	artifacts:expire_in太短	延长有效期或使用dependencies
条件变量未传递	rules:variables作用域限制	在作业内再次定义或使用触发变量

总结

.gitlab-ci.yml通过声明式YAML将CI/CD流程代码化。掌握核心参数------从全局的stages、workflow到作业的script、rules、artifacts、cache------即可构建高效、可维护的流水线。建议从最小配置开始，逐步加入条件逻辑和缓存优化，并善用include和inputs实现配置复用与模板化。

实际编写时，可参考GitLab官方提供的CI/CD示例库和项目中已有的.gitlab-ci.yml文件。