.gitlab-ci.yml 配置文件详解

一.什么是gitlab-ci.yml文件

GitLab提供持续集成服务。如果
将.gitlab-ci.yml文件添加到存储库的根目录，并将GitLab项目配置为使用Runner，则每次提交或推送都会触发CI 管道。
该.gitlab-ci.yml文件是您配置CI如何处理项目的位置。它位于存储库的根目录中。

在对存储库进行任何推送时，GitLab都会查找该.gitlab-ci.yml 文件，并根据该文件的内容在Runners上启动作业。

因为.gitlab-ci.yml是在存储库中并且受版本控制的，所以旧版本仍然可以成功构建，fork可以轻松使用CI，分支可以具有不同的管道和作业，并且您拥有CI的唯一真实来源。您可以.gitlab-ci.yml
在我们的博客中阅读有关使用它的原因的更多信息

工作是：
定义了约束，指出应在什么条件下执行它们。
具有任意名称的顶级元素，并且必须至少包含script子句。
不限制可以定义多少个。

job1:
  script: "execute-script-for-job1"

job2:
  script: "execute-script-for-job2"

作业名称不可用
每个作业必须具有唯一的名称，但是有一些保留keywords名称不能用作作业名称：

image
services
stages
types
before_script
after_script
variables
cache
include

二 配置参数详解

stages

定义pipeline的全部阶段（stage），阶段内所有任务并行执行，全部执行成功开始下一阶段任务，任何阶段内任意job执行失败都会导致pipeline失败，所有stage，job执行成功后pipeline会显示pass。如果未定义stages，则默认有build、test、deploy三个阶段，如果未定义stage，则默认test阶段

stages:
  - build
  - deploy
  - test

variables

在作业级别上定义作业变量。

script

由runner执行的shell脚本

image

使用的docker 镜像，这里docker镜像的地址，也可用：image:name和image:entrypoint。

services

使用docker服务映像。也可用：services:name，services:alias，services:entrypoint，和services:command。

before_script

执行作业之前执行的一段shell脚本

after_script

执行完作业执行一段的shell脚本

stage

定义一个作业阶段（默认值：）test。

only/except

用于设置作业策略以限制创建作业的时间

rules

件列表，用于评估和确定作业的选定属性，以及是否创建该作业。不能与only/ 一起使用except

job:
  script: "echo Hello, Rules!"
  rules:
    - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"'
      when: always
    - if: '$VAR =~ /pattern/'
      when: manual
    - when: on_success

retry

发生故障时可以自动重试作业的时间和次数。

timeout

定义自定义作业级别的超时，该超时优先于项目范围的设置。

include

允许此作业包括外部YAML文件。也可用：include:local，include:file，include:template，和include:remote。

interruptible

定义在通过新的运行使其冗余时是否可以取消作业。

resource_group

限制作业并发。

when

when 用于实现在发生故障或发生故障时运行的作业。

when 可以设置为以下值之一：

on_success-仅当先前阶段中的所有作业都成功（或因为已标记，被视为成功allow_failure）时才执行作业 。这是默认值。
on_failure -仅在前一阶段中的至少一项作业失败时才执行作业。
always -执行作业，而不管先前阶段的作业状态如何。
manual-手动执行作业（在GitLab 8.10中已添加）。在下面阅读有关 手动操作的信息。
delayed-一定时间后执行作业（在GitLab 11.14中已添加）。在下面阅读有关延迟动作的信息

stages:
  - build
  - cleanup_build
  - test
  - deploy
  - cleanup

build_job:
  stage: build
  script:
    - make build

cleanup_build_job:
  stage: cleanup_build
  script:
    - cleanup build when failed
  when: on_failure

test_job:
  stage: test
  script:
    - make test

deploy_job:
  stage: deploy
  script:
    - make deploy
  when: manual

cleanup_job:
  stage: cleanup
  script:
    - cleanup after jobs
  when: always

when:manual

手动操作是一种特殊类型的作业，不会自动执行，需要由用户显式启动。手动操作的示例用法是部署到生产环境。可以从管道，作业，环境和部署视图开始手动操作。在环境文档中阅读更多
内容。

手动操作可以是可选的或阻止的。阻止手动操作将在定义该操作的阶段阻止管道的执行。当有人通过单击播放按钮执行阻止手动操作时，可以恢复管道的执行。

当管道被阻塞时，如果设置了“管道成功时合并”，则不会合并。阻塞的管道也确实具有特殊状态，称为手动。使用when:manual语法时，默认情况下手动操作是非阻塞的。如果要进行手动操作阻止，则必须在中添加
allow_failure: false到作业的定义.gitlab-ci.yml。

environment

environment用于定义作业部署到特定环境。如果environment指定且不存在该名称下的环境，则将自动创建一个新环境

environment:url

这是一个可选值，设置该值时，它将在GitLab中的不同位置显示按钮，单击这些按钮会将您带到定义的URL。

在以下示例中，如果作业成功完成，它将在合并请求和环境/部署页面中创建指向的按钮

https://prod.example.com
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
    url: https://prod.example.com

参考文章：
https://docs.gitlab.com/ee/ci/yaml/