持续集成gitlab-ci.yml配置文档基础

时间：2022-09-30 06:21:05人气：次作者：快盘下载我要评论

[TOC]

0x00 简述

答：gitlab-ci全称是gitlab continuous integration的意思就是持续集成;gitlab-ci.yaml是Gitlab-CI做持续集成和发布的执配置文件，里面定义了如何测试、编译、以及部署阶段执行的脚本，该文件的配置高度依赖于项目本身，以及 CI/CD 流水线的需求。即每次在我们push到gitlab的时候，都会触发此脚本

WeiyiGeek.CI/CD流程概览

1.Pipeline 描述:一次 Pipeline 其实相当于一次构建任务，里面可以包含很多个流程，如安装依赖、运行测试、编译、部署测试服务器、部署生产服务器等流程。任何提交或者 Merge Request 的合并都可以触发 Pipeline 构建，如下图所示

+----------------+           +----------+
|                |  trigger  |          |  
| Commit / Merge +---------->+ Pipeline |
|                |           |          |
+----------------+           +----------+

2.Stages 描述:Stages 表示一个构建阶段，也就是上面提到的一个流程。我们可以在一次 Pipeline 中定义多个 Stages，这些 Stages会有以下特点：

1) 所有 Stages 会按照顺序运行，即当一个 Stage 完成后下一个 Stage 才会开始

2) 只有当所有 Stages 完成后，该构建任务 (Pipeline) 才会成功

3) 如果任何一个 Stage 失败，那么后面的 Stages 不会执行，该构建任务 (Pipeline) 失败 Stages 和 Pipeline 的关系如下所示：

+--------------------------------------------------------+
|                                                        |
| Pipeline                                               |
|                                                        |
| +-----------+  +------------+  +------------+          |
| | Stage 1   |->| Stage 2    |->| Stage 3    |          |
| +-----------+  +------------+  +------------+          |
|                                                        |
+--------------------------------------------------------+

3.Jobs 描述:Jobs 表示构建工作，表示某个 Stage 里面执行的工作。我们可以在 Stages 里面定义多个 Jobs，这些 Jobs 会有以下特点：1) 相同 Stage 中的 Jobs 会并行执行2) 相同 Stage 中的 Jobs 都执行成功时，该 Stage 才会成功3) 如果任何一个 Job 失败，那么该 Stage 失败，即该构建任务 (Pipeline) 失败, 但是可以通过参数设置allow_failure进行跳过

Jobs 和 Stage 的关系如下所示：

+------------------------------------------+
|                                          |
| Stage 1                                  |
|                                          |
| +---------+ +---------+ +---------+      |
| | Job 1   | | Job 2   | | Job 3   |      |
| +---------+ +---------+ +---------+      |
|                                          |
+------------------------------------------+

.gitlab-ci.yml 基础实例:

#构建阶段-任务
stages:
  - analytics
  - test
  - build
  - package
  - deploy

#构建工作job名称
build_analytics:
  #该工作执行阶段
  stage: analytics
  #设置只对master分支有效
  only:
    - master
    - tags
  tags:
    - runner-tag-snoreqube
  script:
    - echo "=============== 开始代码质量检测 ==============="
    - echo "=============== 结束代码质量检测 ==============="

build_test:
  stage: test
  only:
    - master
    - tags
  tags:
    - runner-tag
  script:
    - echo "=============== 开始测试任务 ==============="
    - echo "=============== 结束测试任务 ==============="


build:
  stage: build
  only:
    - master
    - tags
  tags:
    - runner-tag
  script:
    - echo "=============== 开始编译任务 ==============="
    - echo "=============== 结束编译任务 ==============="

package:
  stage: package
  tags:
    - runner-tag
  script:
    - echo "=============== 开始打包任务 ==============="
    - echo "=============== 结束打包任务 ==============="

deploy_test:
  stage: deploy
  tags:
    - runner-tag
  #输出在gitlab-ci中设置的变量
  script:
    - echo "=============== 自动部署到测试服务器 ==============="
    - echo "测试服务器:" ${SERVER_TEST}
  #环境变量
  environment:
    name: test
    url: https://staging.example.com

deploy_test_manual:
  stage: deploy
  tags:
    - runner-tag
  script:
    - echo "=============== 手动部署到测试服务器 ==============="
  environment:
    name: test
    url: https://staging.example.com
  #设置条件 manual 允许失败  
  when: manual

deploy_production_manual:
  stage: deploy
  tags:
    - runner-tag
  script:
    - echo "=============== 手动部署到生产服务器 ==============="
    - echo "测试服务器:" ${SERVER_TEST}
  environment:
    name: production
    url: https://staging.example.com
  when: manual

0x01 配置文档

描述:本章主要用于描述 .gitlab-ci.yml 的语法，. gitlab-ci.yml 文件被用来管理项目的 runner 任务。任务是由Runners接管并且由服务器中runner执行。更重要的是每一个任务的执行过程都是独立运行的,这将意味着上个脚本产生的变量是无法在下一个任务脚本中进行使用。

下面列出保留字段，这些保留字段不能被定义为 job 名称：

关键字 是否必须   描述
image 否        用于docker镜像，查看docker文档
services 否 	   用于docker服务，查看docker文档
stages 否       定义构建阶段
types 否        stages 的别名(已废除)
before_script 否  定义在每个job之前运行的命令
after_script 否   定义在每个job之后运行的命令
variable 否      定义构建变量
cache 否         定义一组文件列表，可在后续运行中使用

开始构建之前YAML文件定义了一系列带有约束说明的任务，用下面这个例子来说明：

image: ruby:2.1
services:
  - postgres

before_script:
  - bundle install

after_script:
  - rm secrets

stages:
  - build
  - test
  - deploy

job1:
  stage: build
  script:
    - execute-script-for-job1
  only:
   - master
  tags:
    - docker

job2:
  stage: deploy
  script: "execute-script-for-job2"

上面这个例子就是带有四个独立任务的CI配置，每个任务分别执行不同的命令，可以看出这些任务都是以任务名开始并且至少要包含 script 部分，并且script 可以直接执行系统命令(例如：./configure;make;make install)或者是直接执行脚本(test.sh)需要注意其执行权限；

gitlab-ci.yml指令约束说明

image和services

这两个关键字允许使用一个自定义的Docker镜像和一系列的服务，并且可以用于整个job周期。详细配置文档请查看：https://docs.gitlab.com/ce/ci/docker/README.html

before_script

用来定义所有job之前运行的命令，包括deploy(部署) jobs，但是在修复artifacts之后。它可以是一个数组或者是多行字符串。

after_script

用来定义所有job之后运行的命令。它必须是一个数组或者是多行字符串

stages

前面简述了stages与pipelins之键的关系，它用来定义可以被job调用的stages。stages的规范允许有灵活的多级pipelines，stages中的元素顺序决定了对应job的执行顺序。

1.相同stage的job可以平行执行。

2.下一个stage的job会在前一个stage的job成功后开始执行。

#例如上面stages构建阶段任务的例子
1. 首先，所有 build 的jobs都是并行执行的。
2. 所有 build 的jobs执行成功后， test 的jobs才会开始并行执行。
3. 所有 test 的jobs执行成功， deploy 的jobs才会开始并行执行。
4. 所有的 deploy 的jobs执行成功，commit才会标记为 success
5. 任何一个前置的jobs失败了，commit会标记为 failed 并且下一个stages的jobs都不会执行

#有两个特殊的例子值得一提：
1. 如果 .gitlab-ci.yml 中没有定义 stages ，那么job's stages 会默认定义为 build ， test 和 deploy 。
2. 如果一个job没有指定 stage ，那么这个任务会分配到 test stage。

variables GItLab CI 允许在 .gitlab-ci.yml 文件中添加变量，并在job环境中起作用。因为这些配置是存储在git仓库中，所以最好是存储项目的非敏感配置，例如：

variables:
DATABASE_URL:"postgres://postgres@postgres/WeiyiGeek"

这些变量可以被后续的命令和脚本使用。服务容器也可以使用YAML中定义的变量，因此我们可以很好的调控服务容器。变量也可以定义成job level。除了用户自定义的变量外，Runner也可以定义它自己的变量例如 CI_COMMIT_REG_NAME 它的值表示用于构建项目的分支或tag名称。除了在 .gitlab-ci.yml 中设置变量外，还有可以通过GitLab的CI/CD界面上设置私有变量。

cache 用来指定需要在job之间缓存的文件或目录。只能使用该项目工作空间内的路径,从GitLab 9.0开始，pipelines和job就默认开启了缓存,如果 cache 定义在jobs的作用域之外，那么它就是全局缓存，所有jobs都可以使用该缓存。

#局部缓存
#缓存 binaries 和 .config 中的所有文件：
rspec:
  script: test
  cache:
    paths:
      - binaries/
      - .config

#缓存git中没有被跟踪的文件：
rspec:
  script: test
  cache:
    untracked: true

#全局缓存
#job中优先级高于全局的。下面这个 rspec job中将只会缓存 binaries/ 下的文件：
cache:
  paths:
    - my/files

rspec:
  script: test
  cache:
    key: rspec
    paths:
      - binaries/

如果你不同的jobs缓存不同的文件路径，必须设置不同的cache:key，否则缓存内容将被重写。缓存key指令允许我们定义缓存的作用域(亲和性)，可以是所有jobs的单个缓存，也可以是每个job，也可以是每个分支或者是任何你认为合适的地方，并且cache:key 可以使用任何的预定义变量。默认key是默认设置的这个项目缓存，因此默认情况下，每个pipelines和jobs中可以共享一切，从GitLab 9.0开始。

#缓存每个job：
cache:
  key: "$CI_JOB_NAME"
  untracked: true

#缓存每个分支：
cache:
  key: "$CI_COMMIT_REF_NAME"
  untracked: true

#缓存每个job且每个分支：
cache:
  key: "$CI_JOB_NAME/$CI_COMMIT_REF_NAME"
  untracked: true

#缓存每个分支且每个stage：
cache:
  key: "$CI_JOB_STAGE/$CI_COMMIT_REF_NAME"
  untracked: true

#如果使用的Windows Batch(windows批处理)来跑脚本需要用 % 替代 $ ：
cache:
  key: "%CI_JOB_STAGE%/%CI_COMMIT_REF_NAME%"
  untracked: true

_注意_：缓存是在jobs之前进行共享的。缓存只是尽力而为之，所以别期望缓存会一直存在。查看更多详细内容，请查阅GitLab Runner。

Jobs .gitlab-ci.yml 允许指定无限量jobs。每个jobs必须有一个唯一的名字，而且不能是上面提到的关键字。job由一列参数来定义jobs的行为。

job_name:
  script:
    - rake spec
    - coverage
  stage: test
  only:
    - master
  except:
    - develop
  tags:
    - ruby
    - postgres
  allow_failure: true

#指令说明
script yes #Runner执行的命令或脚本
image no   #所使用的docker镜像，查阅使用docker镜像
services no #所使用的docker服务，查阅使用docker镜像
stage no #定义job stage（默认： test ）
type no #stage 的别名（已弃用）
variables #no 定义job级别的变量
only no #定义一列git分支，并为其创建job
except no #定义一列git分支，不创建job
tags no #定义一列tags用来指定选择哪个Gitlab-Runner（同时Runner也要设置tags）
allow_failure no #允许job失败。失败的job不影响commit状态
when no  #定义何时开始job 可以是 on_success ， on_failure ， always 或者 manual
dependencies no #定义job依赖关系，这样他们就可以互相传递artifacts
cache no #定义应在后续运行之间缓存的文件列表
before_script no #重写一组在作业前执行的命令
after_script no #重写一组在作业后执行的命令
environment no #定义此作业完成部署的环境名称
coverage no #定义给定作业的代码覆盖率设置

script 是Runner执行的脚本，该参数也可以用数组包含多个命令：

job:
  script:
    - uname -a
    - bundle exec rspec

有时候 script 命令需要被单引号或者是双引号包裹起来。举个例子，当命令中包含冒号( : )时，script需要被包在双引号中，这样YAML解析器才可以正确解析为一个字符串而不是一个键值对(key:value)。使用这些特殊字符的时候一定要注意：: , { , } , [ , ] , , , & , * , # , ? , | , - , < , > , = , !。

stage stage 允许一组jobs进入不同的stages。jobs在相同的 stage 时会 parallel 同时进行。查阅 stages 更多的用法请查看stages。

only and except only 和 except是两个参数用分支策略来限制jobs构建：

1.only 定义哪些分支和标签的git项目将会被job执行。

2.except 定义哪些分支和标签的git项目将不会被job执行。下面是refs策略的使用规则：

only 和 except 可同时使用,如果 only 和 except 在一个job配置中同时存在，则以 only 为准，跳过except (从下面示例中得出)。

only 和 except 可以使用正则表达式。

only 和 except 允许使用特殊的关键字：branches ， tags 和 triggers 。

only 和 except 允许使用指定仓库地址但不是forks的仓库(查看示例3)。

#(1)在下面这个例子中， job 将只会运行以 issue- 开始的refs(分支)，然而except中设置将被跳过。
job:
  # use regexp
  only:
    - /^issue-.*$/
  # use special keyword
  except:
    - branches

#(2)在下面这个例子中， job 将只会执行有tags的refs，或者通过API触发器明确地请求构建。
job:
# use special keywords
  only:
  - tags
  - triggers

#(3)仓库路径只能用于父级仓库执行jobs而不是forks,将会为所有的分支执行 job ，但master分支除外。
job:
  only:
    - branches@gitlab-org/gitlab-ce
  except:
    - master@gitlab-org/gitlab-ce

Job variables 在job中是可以使用关键字 variables 来定义job变量。它的运行原理跟global-level是一样的，但是它允许设置特殊的job变量, Job变量的优先级关系可查看附录的variables文档说明。当设置了job级别的关键字 variables ，它会覆盖全局YAML和预定义中的job变量。想要关闭全局变量可以在job中设置一个空数组：

job_name:
  variables: []

tags tags 可以从允许运行分配给此项目的所有Gitlab-Runners中选择特定的Runners来执行jobs,tags 可通过tags来指定特殊的Runners来运行jobs：在注册Runner的过程中，我们可以设置Runner的标签，比如 ruby ， postgres ， development 。

job:
  tags:
    - ruby
    - postgres

上面这个示例中，需要确保构建此 job 的Runner必须定义了 ruby 和 postgres 这两个tags,否则报错此作业被卡住，因为没有任何该项目指定标签的 runner 在线。

allow_failure allow_failure 可以用于当你想设置一个job失败的之后并不影响后续的CI组件的时候。失败的jobs不会影响到 commit状态。当开启了允许job失败，所有的intents和purposes里的pipeline都是成功/绿色，但是也会有一个"CI build passed with warnings"信息显示在merge request或commit或job page。这被允许失败的作业使用，但是如果失败表示其他地方应采取其他（手动）步骤。下面的这个例子中:job1 和 job2 将会并列进行，如果 job1 失败了，它也不会影响进行中的下一个stage，因为这里有设置了 allow_failure: true 。

job1:
  stage: test
  script:
    - execute_script_that_will_fail
  allow_failure: true
job2:
  stage: test
  script:
    - execute_script_that_will_succeed
job3:
  stage: deploy
  script:
    - deploy_to_staging

when when 用于实现在发生故障或尽管发生故障仍在运行的作业，可以设置以下值：

1.on_success - 只有前面stages的所有工作成功时才执行(默认值)

2.on_failure - 当前面stages中任意一个jobs失败后执行。

3.always - 无论前面stages中jobs状态如何都执行。

4.manual - 手动执行(GitLab8.10增加)。更多请查看手动操作。

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  #始终执行

脚本说明： 1.只有当build_job失败的时候才会执行 cleanup_build_job 。 2.不管前一个job执行失败还是成功都会执行 cleanup_job 。 3.可以从GitLab界面中手动执行 deploy_jobs 。

补充说明:Manual actions手动操作指令是不自动执行的特殊类型的job, 它们必须要人为启动。手动操作指令可以从pipeline，build，environment和deployment视图中启动。部署到生产环境是手动操作指令的一个很好示例。

手动操作指令可以是可选的或阻塞。在定义了手动执行的那个stage中，手动操作指令将会停止pipline中的自动执行指令。当有人通过点击play按钮来执行需要手动执行的job时，可以来恢复pipeline的执行。当pipeline被阻塞时，即使是pipeline是成功状态也不会merge。被阻塞的pipelines也有一个特殊的状态，叫 manual 。手动操作指令默认是不阻塞的。如果你想要手动操作指令产生阻塞，首先需要在job的配置文件 .gitlab-ci.yml 中添加 allow_failure:false ,可选的手动操作指令默认设置allow_failure:true 。可选动作的状态不影响整个pipeline的状态,手动操作指令被认为是写操作，所以当前用户触发操作时，必须拥有操作保护分支的权限。换句话说，为了触发一个手动操作指令到pipeline中正在运行的指定分支，当前用户必须拥有推送到这分支的权限。