.gitlab-ci.yml参数学习

.gitlab-ci.yml参数


.gitlab-ci.yml

.gitlab-ci.yml 用来配置 CI 用你的项目中做哪些操作,这个文件位于仓库的根目录。

当有新内容 push 到仓库,或者有代码合并后, GitLab 会查找是否有 .gitlab-ci.yml 文件,如果文件存在, Runners 将会根据该文件的内容开始 build 本次 commit 。

.gitlab-ci.yml 使用 YAML 语法, 需要格外注意缩进格式,要用空格来缩进,不能用 tabs 来缩进。


.gitlab-ci.yml 配置参数

关键字 描述
variables 定义环境变量
script 必须参数,运行器需要执行的脚本
image 使用Docker image镜像
services 使用Docker services(服务)镜像
stages 定义流水线所有的阶段
stage 定义作业所处流水线的阶段(默认test阶段)
only 定义哪些分支运行,限制作业在什么上创建
except 限制作业在什么时候不创建
tags 作业使用的Runner运行器的标签
when 什么时候运行作业
environment 作用部署的环境名称
cache 指定需要在job之间缓存的文件或目录
artifacts 归档文件列表,指定成功后应附加到job的文件和目录的列表
dependencies 当前作业依赖的其他作业,你可以使用依赖作业的归档文件
coverage 作业的代码覆盖率
retry 作业失败时,可以自动执行多少次
parallel 指定并行运行的作业实例
trigger 定义下游流水线的触发器
include 作业加载其他YAML文件
pages 上传GitLab Pages的结果
before_script 作业执行前需要执行的命令
after_script 作业执行后需要执行的命令
allow_failure 允许作业失败,失败的作业不影响提交的状态

参数详情

variables 变量
variables 变量的优先级

变量的优先顺序是(从最高到最低):

 触发变量或预定的流水线变量。
 项目级别变量或受保护变量。
 组级别变量或受保护变量。
 YAML定义的作业级变量。
 YAML定义的全局变量。
 部署环境变量。
 预定义的环境变量。

script
script 是作业中唯一必须的关键字参数,是运行器需要执行的脚本。

script:
  	- mvn  package docker:build -q -Dmaven.test.skip=false .......

image
image 指定使用Docker镜像。如 iamge:name

services
services 指定使用Docker镜像服务。如 services:name

Stages
stages 定义流水线全局可使用的阶段,阶段允许有灵活的多级管道,阶段元素的排序定义了作业执行的顺序。

  • 相同 stage 阶段的作业并行运行。
  • 默认情况下,上一阶段的作业全部运行成功后才执行下一阶段的作业。
  • 默认有三个阶段, build 、test 、deploy 三个阶段,即 构建 、测试 、部署 。
  • 如果一个作业未定义 stage 阶段,则作业使用 test 测试阶段。
  • 默认情况下,任何一个前置的作业失败了,commit提交会标记为failed并且下一个stages的作业都不会执行。

stage
stage 定义流水线中每个作业所处的阶段,处于相同阶段的作业并行执行。

when
when 关键字用于实现在作业失败时或发生故障时运行的作业 (when is used to implement jobs that are run in case of failure or despite the failure.)。

when 可以设置以下值:

on_success :只有前面的阶段的所有作业都成功时才执行,这是默认值。
on_failure :当前面阶段的作业至少有一个失败时才执行。
always : 无论前面的作业是否成功,一直执行本作业。
manual :手动执行作业,作业不会自动执行,需要人工手动点击启动作业。
delayed : 延迟执行作业,配合 start_in 关键字一起作用, start_in 设置的值必须小于或等于1小时,start_in 设置的值示例: 10 seconds 、 30 minutes 、 1 hour ,前面的作业结束时计时器马上开始计时。

tags
tags 关键字用于指定 GitLab Runner 运行器使用哪一个运行器来执行作业。

Jobs
Jobs 表示构建工作,表示某个 Stage 里面执行的工作。我们可以在 Stages 里面定义多个 Jobs ,这些 Jobs 会有以下特点:

  • 相同 Stage 中的 Jobs 会并行执行
  • 相同 Stage 中的 Jobs 都执行成功时,该 Stage 才会成功
  • 如果任何一个 Job 失败,那么该 Stage 失败,即该构建任务 (Pipeline) 失败

before_script
before_script 用于定义在所有作业之前需要执行的命令,比如更新代码、安装依赖、打印调试信息之类的事情。

before_script:
	- echo "Before script section"
	- echo "For example you might run an update here or install a build dependency"
	- echo "Or perhaps you might print out some debugging details"

after_script
after_script 用于定义在所有作业(即使失败)之后需要执行的命令,比如清空工作空间。

after_script:
	- echo "After script section"
	- echo "For example you might do some cleanup here"

allow_failure

  • allow_failure 可以用于当你想设置一个作业失败的之后并不影响后续的CI组件的时候。失败的作业不会影响到commit提交状态。
  • 如果允许失败的作业失败了,则相应的作业会显示一个黄色的警告,但对流水线成功与否不产生影响。

only 和 except

only 和 except 用于在创建作业时对作业的限制策略。

  • only 定义了哪些分支或标签(branches and tags)的作业会运行
  • except 定义了哪些分支或标签(branches and tags)的作业不会运行

策略规则:

  • only 和 except 可同时使用,如果在一个作业中同时定义了 only 和 except ,则同时 only except 进行过滤(注意,不是忽略 except 条件) 。
  • only 和 except 可以使用正则表达式。
  • only 和 except 允许指定用于过滤forks作业的存储库路径。
  • only 和 except 中可以使用特殊的关键字,如 branches 、 tags 、 api 、 external 、 pipelines 、 pushes 、 schedules 、 triggers 、 web 、 merge_requests 、 chats 等。

only 和 except 中可以使用特殊的关键字:

关键字 描述释义
branches 当一个分支被push上来
tags 当一个打了tag标记的Release被提交时
api 当一个pipline被第二个piplines api所触发调起(不是触发器API)
external 当使用了GitLab以外的外部CI服务,如Jenkins
pipelines 针对多项目触发器而言,当使用CI_JOB_TOKEN, 并使用gitlab所提供的api创建多个pipelines的时候
pushes 当pipeline被用户的git push操作所触发的时候
schedules 针对预定好的pipline计划而言(每日构建一类)
triggers 用触发器token创建piplines的时候
web 在GitLab WEB页面上Pipelines标签页下,按下run pipline的时候
merge_requests 当合并请求创建或更新的时候
chats 当使用GitLab ChatOps 创建作业的时候

only 和 except 高级用法

  • only 和 except 支持高级策略,refs 、 variables 、 changes 、 kubernetes 四个关键字可以使用。

  • 如果同时使用多个关键字,中间的逻辑是 逻辑与AND 。

     only:refs/except:refs
    
  • refs 策略可以使用 only 和 except 基本用法中的关键字。

下面这个例子中,deploy作业仅当流水线是计划作业或者在master主干运行:

deploy:
 	only:
  		refs:
 	 		- master
  	 		- schedules

only:kubernetes/except:kubernetes

  • kubernetes 策略仅支持 active 关键字。
    下面这个例子中,deploy作业仅当kubernetes服务启动后才会运行:

     deploy:
     	only:
     		kubernetes: active
    

only:variables/except:variables

  • variables 关键字用来定义变量表达式,你可以使用预定义变量、项目、组、环境变量来评估一个作业是否需要创建或运行。
    下面这个例子使用了变量表达式:

     deploy:
     script: cap staging deploy
     only:
     	refs:
     		- branches
     	variables:
     		- $RELEASE == "staging"
     		- $STAGING
    

    下面这个例子,会根据提交日志信息来排除某些作业:

     end-to-end:
     	script: rake test:end-to-end
     	except:
     		variables:
     			- $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/
    

only:changes/except:changes

  • changes 策略表明一个作业只有在使用 git push 事件使文件发生变化时执行。

下面这个例子中,deploy作业仅当流水线是计划作业或者在master主干运行:

docker build:
	script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
	only:
		changes:
  			- Dockerfile
  			- docker/scripts/*
  			- dockerfiles/**/*
  			- more_scripts/*.{rb,py,sh}

上面这个例子中,一旦 Dockerfile 文件发生变化,或者 docker/scripts/ 目录下的文件发生变化,或者 dockerfiles/ 目录下的文件或目录发生变化,或者 more_scripts/ 目录下 rb,py,sh 等脚本文件发生变化时,就会触发Docker构建。

  • 也可以使用 glob模式匹配 来匹配根目录下的文件,或者任何目录下的文件。

如下示例:

test:
	script: npm run test
	only:
		changes:
  			- "*.json"
  			- "**/*.sql"

在上面的示例中,glob模式匹配 的字符串需要使用双引号包裹起来,否则会导致 .gitlab-ci.yml 解析错误。

下面这个例子,当md文件发生变化时,会忽略CI作业:

build:
	script: npm run build
	except:
		changes:
  			- "*.md"
  			- 

在合并请求中使用 change 策略:

docker build service one:
		script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG .
		only:
			refs:
  				- merge_requests
			changes:
  				- Dockerfile
  				- service-one/**/*

上面这个例子中,一旦合并请求中修改了 Dockerfile 文件或者修改了 service 目录下的文件,都会触发Docker构建。


示例

#定义 stages(阶段)。任务将按此顺序执行。

  • stages:

     - build
     - test
     - deploy
    

#定义 job(任务)

  • job1:

    stage: test
    tags:

     -XX #只有标签为XX的runner才会执行这个任务
    

    only:

     - dev #只有dev分支提交代码才会执行这个任务。也可以是分支名称或触发器名称
     - /^future-.*$/ #正则表达式,只有future-开头的分支才会执行
    

    script:

     - echo "I am job1"
     - echo "I am in test stage"
    

#定义 job

  • job2:

    stage: test #如果此处没有定义stage,其默认也是test
    only:

     - master #只有master分支提交代码才会执行这个任务
    

    script:

     - echo "I am job2"
     - echo "I am in test stage"
    

    allow_failure: true #允许失败,即不影响下步构建


#定义 job

  • job3:

    stage: build
    except:

     - dev #除了dev分支,其它分支提交代码都会执行这个任务
    

    script:

     - echo "I am job3"
     - echo "I am in build stage"
    

#定义 job

  • . job4:#对于临时不想执行的job,可以选择在前面加个".",这样就会跳过此步任务,否则你除了要注释掉这个job4外,还需要注释上面为deploy的stage

    stage: deploy
    script:

     - echo "I am job4"
    

#下面几个都相当于全局变量,都可以添加到具体job中,这时会被子job的覆盖

before_script:

- echo "每个job之前都会执行"
- export MVN_HOME
- export JAVA_HOME
- java -version
- sh /home/gitlab-runner/kill.sh

after_script:

- echo "每个job之后都会执行"

variables: 变量

  • DATABASE_URL: “postgres://postgres@postgres/my_database”
    在job中可以用${DATABASE_URL}来使用这个变量。
    常用的预定义变量有

     CI_COMMIT_REF_NAME(项目所在的分支或标签名称)
     CI_JOB_NAME(任务名称)
     CI_JOB_STAGE(任务阶段)
    
  • GIT_STRATEGY: “none”
    #GIT策略,定义拉取代码的方式。

     有3种:clone/fetch/none。
     默认为clone,速度最慢,每步job都会重新clone一次代码。
     一般将它设置为none,
     在具体任务里设置为fetch
    

cache: 缓存

#因为缓存为不同管道和任务间共享,可能会覆盖,所以有时需要设置key

key: ${CI_COMMIT_REF_NAME} # 启用每分支缓存。

key: "$CI_JOB_NAME/$CI_COMMIT_REF_NAME" # 启用每个任务和每个分支缓存。

untracked: true #缓存所有Git未跟踪的文件

你可能感兴趣的:(.gitlab-ci.yaml,gitlab)