gitlab CI/CD持续集成

Git CI/CD

目录

• Git CI/CD
  • 一、什么Gitlab CI
    • 优势
  • 二、环境安装
    • 1、安装gitlab（docker版）——管理员管理
    • 2、安装Gitlab runner——开发人员管理
      • 2.1、docker版
      • 2.2、主机版
      • 2.3、问题记录
    • 3、gitlab runner关联gitlab（gitlab上注册runner）
    • 4、创建共享runner
    • 5、激活runner（已激活则忽略）
    • 6、注册成功
    • 7、避免重复拉取镜像
  • 三、概念
    • 1、Pipeline
    • 2、stages
    • 3、Jobs
  • 四、主机、runner、executor关系
  • 五、yml配置文件
    • 1、yml示例
    • 2、关键字
    • 3、关键字解析
      • 3.1、script
      • 3.2、after_script
      • 3.3、variables
      • 3.4、script
      • 3.5、only 与 except
      • 3.6、artifacts
      • 3.7、image
      • 3.8、tags
      • 3.9、cache
      • 3.10、variables
    • 4、CI已定义变量

一、什么Gitlab CI

GitLab CI 是 GitLab 为了提升其在软件开发工程中作用，完善 DevOPS 理念所加入的 CI/CD 基础功能。可以便捷的融入软件开发环节中。通过 GitLab CI 可以定义完善的 CI/CD Pipeline。

优势

• GitLab CI 是默认包含在 GitLab 中的，我们的代码使用 GitLab 进行托管，这样可以很容易的进行集成
• GitLab CI 的前端界面比较美观，容易被人接受
• 包含实时构建日志，容易追踪
• 采用 C/S 的架构，可方面的进行横向扩展，性能上不会有影响
• 使用 YAML 进行配置，任何人都可以很方便的使用。

二、环境安装

1、安装gitlab（docker版）——管理员管理

docker pull gitlab/gitlab-ce

sudo docker run -d  
	-p 443:443 -p 80:80 
    --name gitlab 
    --hostname sgitlab 
    --restart always 
    -v /data/gitlab/config:/etc/gitlab 
    -v /data/gitlab/logs:/var/log/gitlab 
    -v /data/gitlab/data:/var/opt/gitlab 
    gitlab/gitlab-ce

• 配置

  按上面的方式，gitlab容器运行没问题，但在gitlab上创建项目的时候，生成项目的URL访问地址是按容器的hostname来生成的，也就是容器的id。作为gitlab服务器，我们需要一个固定的URL访问地址，于是需要配置gitlab.rb（宿主机路径：/data/gitlab/config/gitlab.rb）

  sudo vim /data/gitlab/config/gitlab.rb
  

  # 配置http协议所使用的访问地址,不加端口号默认为80
  external_url 'http://192.168.199.115'
  
  # 配置ssh协议所使用的访问地址和端口
  gitlab_rails['gitlab_ssh_host'] = '192.168.199.115'
  gitlab_rails['gitlab_shell_ssh_port'] = 222 # 此端口是run时22端口映射的222端口
  

启动成功后，访问gitlab会强制修改root密码。

2、安装Gitlab runner——开发人员管理

2.1、docker版

原文：https://gitlab.com/gitlab-org/gitlab-runner/blob/master/docs/install/osx.md

gitlab runner为ci / cd提供运行环境， GitLab Runner可以跑在一个单独的机子上，只需要这个机器需要能够访问GitLab服务本身

docker pull  gitlab/gitlab-runner

# 必须将docker.sock挂载进runner容器
sudo docker run -d 
--name gitlab-runner 
--restart always 
-v /var/run/docker.sock:/var/run/docker.sock 
-v /data/gitlab-runner/config:/etc/gitlab-runner 
gitlab/gitlab-runner

2.2、主机版

curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
sudo apt-get install gitlab-runner

# 启用命令启动Runner
sudo gitlab-runner run

2.3、问题记录

gitlab-runner版本问题导致，使用gitlab-runner 12以上即可解决

3、gitlab runner关联gitlab（gitlab上注册runner）

• 获取注册runner时使用的URL与Token，进入项目仓库，Settings --> CI/CD --> Runners --> Specific runners --> URL 、token

• 启动并注册到gitlab

  • 直接执行命令

    # url是上图中的url， token是上图中的token
    docker run --rm -t -i -v `pwd`/gitlab-runner:/etc/gitlab-runner --name gitlab-runner gitlab/gitlab-runner register 
      --non-interactive 
      --executor "docker" 
      --docker-privileged  
      --docker-image nginx:1.19.2 
      --url "http://10.0.2.91/" 
      --registration-token "Ys7zVmpsxtqDxf79Xupv" 
      --description "shared-docker-runner" 
      --tag-list "shared_docker" 
      --run-untagged 
      --locked="true"
    

  • 进入runner容器执行

    # 进入容器
    docker exec -it gitlab-runner /bin/bash
    
    # 运行以下注册命令
    gitlab-runner register
    
    # 输入Gitlab实例的地址
    Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
    http://10.0.2.11  # 端口采用默认的80，否则需要加上端口，比如 http://10.0.2.11:8090
    
    # 输入token
    Please enter the gitlab-ci token for this runner
    VobqwqSTYvm69Ln3sVcm
    
    # 输入描述信息
    Enter a description for the runner:
    [2f5631485bf3]: this is the description
    
    # 输入tag
    Enter tags for the runner (comma-separated):
    test_tag
    
    # 输入Ruuner的执行者
    Enter an executor: docker-ssh, ssh, virtualbox, docker-ssh+machine, kubernetes, custom, docker, parallels, shell, docker+machine:
    shell
    
    # 如果上面executor为docker，需要你在后续项目根部的.gitlab-ci.yml中  指定具体docker版本
    #Enter the default Docker image (for example, ruby:2.6):
    #alpine:latest
    

4、创建共享runner

共享runner的url与token，在root账户下可见，其余同指定runner相同

5、激活runner（已激活则忽略）

绿色表示已激活

sudo gitlab-runner verify
sudo gitlab-runner restart

6、注册成功

• 注册成功，在/etc/gitlab-runner/config.toml中可查看已注册的所有runner

7、避免重复拉取镜像

在/etc/gitlab-runner/config.toml的runners.docker中添加pull_policy = "if-not-present"

三、概念

1、Pipeline

Pipeline 相当于一个构建任务，里面可以包含多个stage(流程)，如依赖安装、编译、测试、部署等。
任何提交或者 Merge Request 的合并都可以触发 Pipeline

2、stages

Stage 表示构建的阶段，即上面提到的流程.

• 所有 Stages 按顺序执行，即当一个 Stage 完成后，下一个 Stage 才会开始
• 任一 Stage 失败，后面的 Stages 将永不会执行，Pipeline 失败
• 只有当所有 Stages 完成后，Pipeline 才会成功

3、Jobs

Job 是 Stage 中的任务.

• 相同 Stage 中的 Jobs 会并行执行
• 任一 Job 失败，那么 Stage 失败，Pipeline 失败
• 相同 Stage 中的 Jobs 都执行成功时，该 Stage 成功

四、主机、runner、executor关系

• 每个excutor中的环境在创建runner时指定，可以包括以下的环境（使用docker时需要指定默认镜像）：

  docker-ssh, ssh, virtualbox, docker-ssh+machine, kubernetes, custom, docker, parallels, shell, docker+machine

• 如果executor不使用docker，那么会使用runner所在的环境

五、yml配置文件

官方文档： https://docs.gitlab.com/ee/ci/yaml/README.html

1、yml示例

在项目根目录下创建.gitlab-ci.yml，这里的demo对应上图配置的runner

• gitlab-runner使用docker安装
• 容器中手动安装python3、zip

stages:
  - test
  - deploy

test:
  stage: test
  tags:
    - docker_runner
  script:
    - python3 test_py.py
    
tttt:
  stage: test
  tags:
    - docker_runner
  script:
    - python3 test_file.py

pack:
  stage: deploy
  tags:
    - docker_runner
  script:
    - zip aaa.zip b.txt

2、关键字

• test、tttt、pack是Job名字
• script是要执行的脚本，每个job中必须包含
• tags是指定需要在哪些tag对应的runner中执行

关键字	是否必须	描述
script	yes	Runner执行的命令或脚本。可以包含多条命令
image	no	使用的docker镜像。详见
services	no	使用的docker服务。详见
stage	no	定义job stage（默认：test）
type	no	stage的别名（已弃用）
variables	no	定义job级别的变量
only	no	定义一列git分支，并为其创建job
except	no	定义一列git分支，不创建job
tags	no	定义一列tags，用来指定选择哪个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	定义给定作业的代码覆盖率设置

• only 和 except中关键字

  • only：定义一列git分支，并为其创建job
  • except：定义一列git分支，不创建job

  关键字	描述
  branches	当一个分支被push上来
  tags	当一个打了tag的分支被push上来
  api	当一个pipline被piplines api所触发调起，详见piplines api
  external	当使用了GitLab以外的CI服务
  pipelines	针对多项目触发器而言，当使用CI_JOB_TOKEN并使用gitlab所提供的api创建多个pipelines的时候
  pushes	当pipeline被用户的git push操作所触发的时候
  schedules	针对预定好的pipline而言（每日构建一类）
  triggers	用token创建piplines的时候
  web	在GitLab页面上Pipelines标签页下，你按了run pipline的时候

3、关键字解析

3.1、script

这里不需要使用git clone ....克隆当前的项目，来进行操作，因为在流水线中，每一个的job的执行都会将项目下载，恢复缓存这些流程，不需要你再使用脚本恢复。

• script的工作目录就是当前项目的根目录
• script是一个job的必填内容，不可或缺。一个job最少有二个属性，一个是job name

3.2、after_script

before_script 和 script 在一个上下文中是串行执行的，after_script 是独立执行的。所以根据执行器(在runner注册的时候，可以选择执行器，docker,shell 等)的不同，工作树之外的变化可能不可见，例如，在before_script中执行软件的安装。

你可以在任务中定义 before_script，after_script，也可以将其定义为顶级元素，定义为顶级元素将为每一个任务都执行相应阶段的脚本或命令。

3.3、variables

GitLab CI允许你为.gitlab-ci.yml增加变量，该变量将会被设置入任务环境。这些变量是你存储在git仓库里，并且非敏感的项目配置

3.4、script

script是一段由Runner执行的shell脚本

• script命令包含了YAML中的语法时需要被单引号或者双引号所包裹。例如：当命令中包涵冒号的时候，该命令需要被引号所包裹。

• 当命令中包涵以下字符时需要注意打引号: : { } [ ] , & * # ? | - < > = ! % @

3.5、only 与 except

• only：定义了job需要执行的所在branch或者tag
• except：定义了job不会执行的所在branch或者tag
  • only和except如果都存在在一个job声明中，则所需引用将会被only和except所定义的分支过滤.
  • only和except允许使用正则
  • only和except允许使用指定仓库地址，但是不forks仓库

例如：

job:
    # 使用正则
    only:
        - /^issue-.*$/
    #
    except:
        - branches

3.6、artifacts

artifacts 被用于在 job 作业成功后将制定列表里的文件或文件夹附加到 job 上，传递给下一个 job ，如果要在两个 job 之间传递 artifacts，你必须设置dependencies。

artifacts则是将某个文件上传到GitLab提供下载或后续操作使用。artifacts会先传到GitLab服务器，然后需要时再重新下载，所以这部分也可以在GitLab下载和浏览。

• 例子

  • 传递所有文件

    job:
      stage: deploy
      tags:
        - test_ci
      script:
        - zip aaa.zip ./*
      artifacts:
        paths:
          - aaa.zip
    

  • 传递所有git没有追踪的文件

    artifacts:
        untracked: true
    

• 关键字

  • name

    name指令允许你对artifacts压缩包重命名，你可以为每个artifect压缩包都指定一个特别的名字，这样对你在gitlab上下载artifect的压缩包有用。下载时默认是artifact.zip

    job:
        artifacts:
            name: "upgrade"   # 下载时文件名为 upgrade.zip
    

  • when

    用于job失败或者未失败时使用。

    artifacts:when能设置以下值：

    1. on_success 这个值是默认的，当job成功时，上传artifacts
    2. on_failure 当job执行失败时，上传artifacts
    3. always 不管失败与否，都上传

    job:
        artifacts:
            when: on_failure    #当失败时上传artifacts
    

  • expire_in

    expire_in 用于设置 artifacts 上传包的失效时间。如果不设置，artifacts 的打包是永远存在于 gitlab上 的。当指定 artifacts 过期时间的时候, 在该期间内，artifacts 包将储存在 gitLab 上。并且你可以在 job 页面找到一个 keep 按钮，按了以后可以覆盖过期时间，让 artifacts 永远存在。过期之后，用户将无法访问到 artifacts 包

    时间格式：

    '3 mins 4 sec'
    '2 hrs 20 min'
    '2h20min'
    '6 mos 1 day'
    '47 yrs 6 mos and 4d'
    '3 weeks and 2 days'
    

    job:
        artifacts:
            expire_in: 1 day # 一天后过期
    

如下图所示，如果配置了artifacts，那么在gitlab的pipelines中可以下载对应pipeline生成的文件。

3.7、image

指定一个基础Docker镜像作为基础运行环境，经常用到的镜像有node、 nginx

job:
	image: nginx:latest
	script: yum install python3

3.8、tags

用于指定Runner,tags的取值范围是在该项目可见的runner tags中，可以在Setting --> CI/CD --> Runner 中查看的到。

如果不设置，则默认使用公有Runner去执行流水线

install:
  tags:
    - hello-vue
    - docker
  script:
    - npm config set sass_binary_site https://npm.taobao.org/mirrors/node-sass/
    - npm install --registry=http://registry.npm.taobao.org

3.9、cache

cache是将当前工作环境目录中的一些文件/文件夹存储起来，用于在各个任务初始化的时候恢复。避免多个下载同样的包，能够大大优化流水线效率。

在java项目中经常把maven下载的包缓存起来。在python中经常将依赖包缓存起来。

例如，缓存所有binaries目录下以.apk结尾的文件

rspec:
  script: test
  cache:
    paths:
      - binaries/*.apk
      - .config

3.10、variables

自定义变量，如果该变量位于最高级别，则该变量在全局范围内可用，并且所有job都可以使用它。如果是在job中定义的，则只有该job可以使用它

variables:
  TEST_VAR: "All jobs can use this variable's value"

job:
  variables:
    TEST_VAR: "Only job  can use this variable's value"
  script:
    - echo $TEST_VAR and $TEST_VAR_JOB

4、CI已定义变量

Variable	GitLab	Runner	Description
CI	all	0.4	标识该job是在CI环境中执行
CI_COMMIT_REF_NAME	9.0	all	用于构建项目的分支或tag名称
CI_COMMIT_REF_SLUG	9.0	all	先将$CI_COMMIT_REF_NAME的值转换成小写，最大不能超过63个字节，然后把除了0-9和a-z的其他字符转换成-。在URLs和域名名称中使用。
CI_COMMIT_SHA	9.0	all	commit的版本号
CI_COMMIT_TAG	9.0	0.5	commit的tag名称。只有创建了tags才会出现。
CI_DEBUG_TRACE	9.0	1.7	debug tracing开启时才生效
CI_ENVIRONMENT_NAME	8.15	all	job的环境名称
CI_ENVIRONMENT_SLUG	8.15	all	环境名称的简化版本，适用于DNS，URLs，Kubernetes labels等
CI_JOB_ID	9.0	all	GItLab CI内部调用job的一个唯一ID
CI_JOB_MANUAL	8.12	all	表示job启用的标识
CI_JOB_NAME	9.0	0.5	.gitlab-ci.yml中定义的job的名称
CI_JOB_STAGE	9.0	0.5	.gitlab-ci.yml中定义的stage的名称
CI_JOB_TOKEN	9.0	1.2	用于同GitLab容器仓库验证的token
CI_REPOSITORY_URL	9.0	all	git仓库地址，用于克隆
CI_RUNNER_DESCRIPTION	8.10	0.5	GitLab中存储的Runner描述
CI_RUNNER_ID	8.10	0.5	Runner所使用的唯一ID
CI_RUNNER_TAGS	8.10	0.5	Runner定义的tags
CI_PIPELINE_ID	8.10	0.5	GitLab CI 在内部使用的当前pipeline的唯一ID
CI_PIPELINE_TRIGGERED	all	all	用于指示该job被触发的标识
CI_PROJECT_DIR	all	all	仓库克隆的完整地址和job允许的完整地址
CI_PROJECT_ID	all	all	GitLab CI在内部使用的当前项目的唯一ID
CI_PROJECT_NAME	8.10	0.5	当前正在构建的项目名称（事实上是项目文件夹名称）
CI_PROJECT_NAMESPACE	8.10	0.5	当前正在构建的项目命名空间（用户名或者是组名称）
CI_PROJECT_PATH	8.10	0.5	命名空间加项目名称
CI_PROJECT_PATH_SLUG	9.3	all	$CI_PROJECT_PATH小写字母、除了0-9和a-z的其他字母都替换成-。用于地址和域名名称。
CI_PROJECT_URL	8.10	0.5	项目的访问地址（http形式）
CI_REGISTRY	8.10	0.5	如果启用了Container Registry，则返回GitLab的Container Registry的地址
CI_REGISTRY_IMAGE	8.10	0.5	如果为项目启用了Container Registry，它将返回与特定项目相关联的注册表的地址
CI_REGISTRY_PASSWORD	9.0	all	用于push containers到GitLab的Container Registry的密码
CI_REGISTRY_USER	9.0	all	用于push containers到GItLab的Container Registry的用户名
CI_SERVER	all	all	标记该job是在CI环境中执行
CI_SERVER_NAME	all	all	用于协调job的CI服务器名称
CI_SERVER_REVISION	all	all	用于调度job的GitLab修订版
CI_SERVER_VERSION	all	all	用于调度job的GItLab版本
ARTIFACT_DOWNLOAD_ATTEMPTS	8.15	1.9	尝试运行下载artifacts的job的次数
GET_SOURCES_ATTEMPTS	8.15	1.9	尝试运行获取源的job次数
GITLAB_CI	all	all	用于指示该job是在GItLab CI环境中运行
GITLAB_USER_ID	8.12	all	开启该job的用户ID
GITLAB_USER_EMAIL	8.12	all	开启该job的用户邮箱
RESTORE_CACHE_ATTEMPTS	8.15	1.9	尝试运行存储缓存的job的次数

推荐博文：

GitLab-CI中的artifacts使用研究：http://zacksleo.top/archives/

Gitlab CI 使用高级技巧：https://www.jianshu.com/p/3c0cbb6c2936

一文搞定gitlab的环境搭建、配置CI/CD、自动构建docker镜像：https://www.cnblogs.com/hzhhhbb/p/13966904.html?share_token=4dfe4dbe-caac-4437-b2b4-ea59b03c67d1