Gitlab CI 入门指南

王 茂南
王 茂南
王 茂南
3276
文章
75
评论
2025年5月10日07:18:52
评论 5227字阅读17分25秒
摘要本文简单介绍 Gitlab CI 的简单使用，介绍其的配置语法，最后会包含一个 gitlab page 生成的例子。

简介

CI（continuous integration）表示持续集成。他的基本思想是让一个自动化程序监测一个或是多个源代码仓库是否有变更。当有变更推送（push/merge）到仓库的时候，他会检测到更改，并进行相关的单元测试等。

Gitlab-CI 是 Gitlab 中内置的进行持续集成的工具。它提供了一个叫 Gitlab-runner 的软件，只要在对应的平台（机器或 docker ）上下载并运行这个命令行软件，并输入从 gitlab 交互界面获取的 token，就可以把当前机器和对应的 gitlab-ci 流程绑定，也即：每次跑 ci 都在这个平台上进行。

Gitlab-CI 的所有流程都是可视化的，每个流程节点的状态可以在 gitlab 的交互界面上看到，包括执行成功或失败。如下图所示：

Gitlab CI 入门指南

本文会对 Gitlab-CI 的使用进行详细的介绍。

参考资料

 

Gitlab-CI 涉及的抽象概念

Pipeline 和 Job

Pipeline 是 Gitlab 根据项目的 .gitlab-ci.yml 文件执行的流程，它由许多个任务节点组成，而这些Pipeline 上的每一个任务节点，都是一个独立的 Job。

在配置 yml 文件时，每个 Job 都会配置一个 stage 属性，来表示这个 Job 所处的阶段。一个 Pipleline 有若干个 stage，每个 stage 上有至少一个 Job（一个 stage 可以有多个 jobs），如下图所示，这张图会在后面有一个详细的说明：

Gitlab CI 入门指南

 

Runner

Runner 可以理解为在特定的机器上，根据 .gitlab-ci.yaml 文件，对项目执行 pipeline 的程序。Runner 可以分为两种：

  • Shared Runner（共享型），所有项目都可以使用，只可以由系统管理员创建。通常情况下，是Gitlab 平台提供的免费使用的 runner 程序，它由 Google 云平台提供支持，每个开发团队有十几个。对于公共开源项目是免费使用的，如果是私人项目则有每月 2000 分钟的 CI 时间上限。
  • Specific Runner（指定型），只有特定的项目可以使用，自己部署服务器，然后注册为 Runner。gitlab 给我们提供了一个叫 gitlab-runner 的命令行软件，只要在对应机器上下载安装这个软件，并且运行 gitlab-runner register 命令，然后输入从 gitlab-ci 交互界面获取的 token 进行注册, 就可以在自己的机器上远程运行 pipeline 程序了。

 

YML 文件的基本语法规则

CI 流程的运行控制，决定于项目根目录下编写的配置文件—— .gitlab-ci.yml，正因如此，我们需要掌握 YML 的基本语法规则。YML 是一种编写配置文件的语言，比 JSON 更为简洁和方便，因此，我们首先要掌握的就是 YML 文件的编写语法。

下面是一个最简单的 YML 文件：

  1. install-job: # 注释
  2.   tags:
  3.     - sss
  4.   stage: install
  5.   script:
  6.     - npm install

从中可以看两点：

  • YML 通过缩进组织层级
  • YML 里允许通过 # 符号编写注释

 

YML 中数组的写法

在 YML 中数组使用如下的形式进行书写，

  1. colors
  2.   - red
  3.   - blue
  4.   - yellow

下面是 JSON 中的数组的写法：

  1. { "colors": ["red","blue","yellow"] }

 

YML 中字典的写法

在 YML 中也可以利用缩进来完成字典形式的表达：

  1. people:
  2.   name: zhangsan
  3.   age: 14

这个在 JSON 中等价于下面的形式：

  1. {
  2.   "people": {
  3.      "name": "zhangsan"
  4.      "age": 14
  5.   }
  6. }

需要注意的是，在 YML 中一般不需要给字符串增加双引号或是单引号。

 

.gitlab-ci.yml 常用配置

在了解了 YML 文件的语法格式后，接下来需要了解的就是 .gitlab-ci.yml 独特的配置关键字。这些关键字将在 .gitlab-ci.yml 中使用，并用来控制一个 pipeline 具体的运作过程。下面我们会介绍常见的 .gitlab-ci.yml 中的关键字。

 

image

该关键字指定一个任务（job）所使用的 docker 镜像。例如image: python:latest使用 Python 的最新镜像。或是 image: python:3.7 指定某一个特定版本的 python。

 

stage 与 stages

stages 是定义在 YML 文件在外层的内容，他的值是一个数组，用于定义一个 pipeline 不同的流程节点（可以认为是执行指令的先后顺序）。在每一个 job 中，我们需要指定 stage，从而可以指定不同 job 的执行顺序。看下面的例子：

  1. image: python:3.7
  3. stages: # 这里定义 pipeline
  4.   - build
  5.   - doc
  6.   - test
  8. build_1: # 这里是一个 job
  9.   stage: build
  10.   script:
  11.     - echo $PWD
  13. build_2:
  14.   stage: build # 与 job:build_1 的 stage 相同
  15.   script:
  16.     - echo $PWD
  18. doc_1:
  19.   stage: doc
  20.   script:
  21.     - echo $PWD
  23. test_1:
  24.   stage: test
  25.   script:
  26.     - echo $PWD
  28. test_2:
  29.   stage: test
  30.   script:
  31.     - echo $PWD
  33. test_3:
  34.   stage: test
  35.   script:
  36.     - echo $PWD

最终可以在 gitlab 中可视化的看到如下的 pipeline。可以看到当两个任务对应 stage 相同时，他们会并列。

Gitlab CI 入门指南

 

script

在上面的例子中可以看到每个 job 中都有关键词 script。它是当前 pipeline 节点（某个 job）运行的 shell 脚本（以项目根目录为上下文执行）。

这个 script 是我们控制 CI 流程的核心。我们所有的工作：从安装，编译到部署都是通过script中定义的 shell 脚本来完成的。如果脚本执行成功，pipeline 就会进入下一个 Job 节点，如果执行失败那么 pipeline 就会终止。

下面是一个最简单的 script，打印当前的路径，以及当前文件夹内的文件：

  1. pages:
  2.   stage: doc
  3.   script:
  4.     - echo $PWD
  5.     - echo $(ls .)

 

tags

tags 关键字指定了使用哪个 Runner（哪个机器）去执行我们的任务，注意与下面 only 关键字的 tags 进行区分。这里的 tag 是 git tag。

  1. image: python:3.6
  3. job1:
  4.   only:
  5.     - dev # 只有提交分支是 dev 的时候才触发
  6.   tags:
  7.     - machine1 # 指定哪个机器执行我们的任务
  8.   script:
  9.     - echo $PWD

 

only 和 except

only 和 except 这两个关键词是用来控制任务触发的条件。例如当提交的分支是 master 分支时才触发，则可以按下面这样写：

  1. job1:
  2.   only:
  3.     - master
  4.   script:
  5.     - echo $PWD

或是当提交的分支为 master 或者打了 tags 才触发（及没有 tags 是不会触发的）

  1. # 举这个例子是想说明only关键字之间的关系是”或“关系
  2. job1:
  3.   only:
  4.     - master
  5.     - tags
  6.   script:
  7.     - echo $PWD

 

when

前面说过，stages 关键字可以控制每个任务的执行顺序，且后一个 stage 会等待前一个 stage 执行成功后才会执行。那如果我们想要达到前一个stage失败了，后面的stage仍然能够执行的效果呢？ 这时候when关键字就可以发挥作用了，它一共有五个值：
  • on_success：只有前面 stages 的所有工作成功时才执行，这是默认值。
  • on_failure：当前面 stages 中任意一个 jobs 失败后执行
  • always：无论前面 stages 中 jobs 状态如何都执行
  • manual：手动执行
  • delayed：延迟执行
  1. # 官方示例
  2. stages:
  3.   - build
  4.   - cleanup_build
  5.   - test
  6.   - deploy
  7.   - cleanup
  9. build_job:
  10.   stage: build
  11.   script:
  12.     - make build
  14. # 如果build_job任务失败，则会触发该任务执行
  15. cleanup_build_job:
  16.   stage: cleanup_build
  17.   script:
  18.     - cleanup build when failed
  19.   when: on_failure
  21. test_job:
  22.   stage: test
  23.   script:
  24.     - make test
  26. deploy_job:
  27.   stage: deploy
  28.   script:
  29.     - make deploy
  30.   when: manual
  32. # 总是执行
  33. cleanup_job:
  34.   stage: cleanup
  35.   script:
  36.     - cleanup after jobs
  37.   when: always
 

 

Gitlab Page 生成

Gitlab 会自动将 public 目录（这个目录需要自己创建）下的文件进行发布成 Gitlab Page。下面放一个最简单的例子，整个仓库的目录结构如下所示，有一个 .gitlab-ci.yml 的配置文件，将 html 文件放在 source 文件夹里面：

  1. .
  2. ├── README.md
  3. ├── .gitlab-ci.yml
  4. └── source
  5.     └── index.html

public 文件夹中必须有 index.html 文件。这里index.html可以随意写一下就可以了。我们主要来看一下 .gitlab-ci.yml 的配置文件，里面有 mkdir public 来创建 public 文件夹。

  1. image: python3.6
  3. stages:
  4.   - doc
  6. pages:
  7.   stage: doc
  8.   script:
  9.   - mkdir public # 需要创建 public 文件夹
  10.   - cp -r source/* public/ # 将 source 中的文件移动到 public
  12.   artifacts:
  13.     paths:
  14.     - public
  15.   only:
  16.   - master

上面就是一个最简单的 Gitlab Page 的例子。我们也可以使用 Sphinx 来生成 html 文件，最后将生成的文件移动到 public 文件夹即可。（关于 Sphinx 的使用说明可以参考，Python 文档生成-Sphinx）

 

pages: deploy - No entries extracted

在使用 sphinx 自动生成 gitlab page 的时候，可能会出现以下的报错：

  1. Uploading artifacts...
  2. WARNING: public: no matching files
  3. ERROR: No files to upload

这是因为 public 文件夹内没有文件，所有上传失败。我们需要注意，public 文件夹是在项目的根目录下的（可以理解为一个隐藏的文件夹，他是不会被上传到仓库中去的）。所以我们将文件移动到 public 下的时候，需要返回项目的根目录下，或者移动的时候把路径写全了。

例如我们的项目路径是在 /home/wangmaonan/example/，那么我们的 public 的路径就是 /home/wangmaonan/example/public/，也就是说我们需要把所有的文件移动到上面的路径内。

例如下面是一个自动部署 sphinx 的脚本，可以看到我们直接将 sphinx-build 生成的文件放在 /home/wangmaonan/example/public/这个路径下：

  1. image: python:3.7-alpine
  3. stages:
  4.   - doc
  7. pages:
  8.   stage: doc
  9.   script:
  10.   - pip install -U sphinx
  11.   - pip install -U sphinx_rtd_theme
  12.   - pip install -U recommonmark
  13.   - cd ./doc/source
  14.   - sphinx-build -b html . /home/wangmaonan/example/public
  16.   artifacts:
  17.     paths:
  18.     - public
  19.   only:
  20.   - docs

 

  • 微信公众号
  • 关注微信公众号
  • weinxin
  • QQ群
  • 我们的QQ群号
  • weinxin
王 茂南
  • 本文由 发表于 2025年5月10日07:18:52
  • 转载请务必保留本文链接：https://mathpretty.com/13556.html
匿名

发表评论

匿名网友 填写信息

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen: