.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未跟踪的文件