乐趣区

GitLabRunner入门及常见问题

jiezi

安装 GitLab Runner

本教程的安装环境为 Ubuntu18.04。

  1. 运行以下命令增加 GitLab 官方仓库：

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

  2. 安装最新版本的 GitLab Runner，或者选择特定的版本：

    • 安装最新版本

      sudo apt-get install gitlab-runner

    • 选择特定的版本

      sudo apt-get install gitlab-runner=10.0.0

注册 GitLab Runner

此处是将你的 GitLab Runner 注册到 GitLab page 上，让 GitLab page 可以和你的 Runner 通信。

先决条件

在注册 Runner 之前，你首先需要：

  • 安装好 Runner 的 Linux 主机
  • 从 GitLab page 上获得 token

注册

  1. 运行如下命令：

    sudo gitlab-runner register

  2. 输入 GitLab URL：

    Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com)
https://code.siemens.com/

    注意：你可以通过 GitLab page -> Settings -> CI/CD -> Runners 来获得 URL，当然前提条件是你有权限进入这些页面。

  3. 输入你的注册 token：

    Please enter the gitlab-ci token for this runner  
xxx

    在步骤 2 中你也可以同时看到 token 信息

  4. 输入对这个 Runner 的表述（同时也是这个 Runner 的名字），当然，你也可以稍后在 GitLab page 上修改它：

    Please enter the gitlab-ci description for this runner  
[hostame] my-runner

  5. 输入 Runner 的 tag，稍后你同样可以在 GitLab page 上修改它：

    Please enter the gitlab-ci tags for this runner (comma separated):
my-tag,another-tag

    注意 tag 可以有多个，各 tag 之间用逗号隔开。如果你使用了多个 tag，那么当你想用这个 Runner 时，在 .gitlab-ci.yml 的 tag 字段里也必须明确指明这些 tags。

  6. 输入 Runner 的 executor：

    Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:
docker

    如果你选择 Docker 作为 Runner 的 executor，你还要选择默认的 docker image 来运行 job（当然，你也可以在 .gitlab-ci.yml 里指明你需要用的 image）：

    Please enter the Docker image (eg. ruby:2.1):
alpine:latest

注册完成后你可以在 /etc/gitlab-runner 里发现 config.toml文件，该文件是 Runner 的配置文件

使用 GitLab Runner

  • 直接运行 Runner

    sudo gitlab-runner run

  • 将 Runner 作为一个服务

    1. 将 GitLab Runner 安装为系统服务：

      sudo gitlab-runner install -n "<service-name>" -u <user-name>

    2. 启动服务：

      sudo gitlab-runner start -n "<service-name>"

      注意：这些服务相关的命令是不推荐的并且将会在接下来的版本中删除。

想要了解更多 GitLab Runner 相关的命令，请访问 GitLab Runner Commands.

重要的话题 —— Executor

Shell Executor

以宿主机（此处为 Ubuntu18.04 系统）作为 Runner 的所有 jobs 的执行器。

Runner 将会从远程仓库 pull 你的工程，工程的目录为：<working-directory>/builds/<short-token>/<concurrent-id>/<namespace>/<project-name>。

如果你使用了 cache，那么 cache 将会存在<working-directory>/cache/<namespace>/<project-name>。

想了解更多关于 Shell executor 的内容，请访问 Shell Executor。

Docker Executor

所有 jobs 的执行环境为指定的 docker image 所生成的 container，每个 job 都会生成一个 container 并且在 job 结束后立即销毁。

  • build 和 cache 的存储

    Docker executor 默认将所有的 builds 存储在 /builds/<namespace>/<project-name>（这里的路径是 container 里的路径，Runner 配置文件config.toml 里的 build_dir 字段可以重新指明 build 的目录，默认对应于宿主机的目录是在宿主机的 docker volume 下：/var/lib/docker/volumes/<volume-id>/_data/<project-name>），默认将所有的 caches 存储在 container 里的 /cache 目录（config.toml里的 cache_dir 字段可以重新指明 cache 的目录），注意 build_dir 和cache_dir指向的均是 container 里的目录，要想将 container 里的数据持久化，需要用到 volumes 字段，这个字段的使用和 docker volume 的使用是类似的，只需在 config.toml 的[runner.docker]部分添加 volumes = ["/cache", "<host_dir:container_dir>:rw"] 即可实现 container 里 /cache 目录数据的永久保存以及将 host 目录挂载到相应的 container 目录并具有读写的功能。

  • Pull policies

    当你使用 docker 或 docker+machine executors 时，你可以通过设置pull_policy 来决定 Runner 如何 pull docker image。pull_policy有三种值：
    always —— Runner 始终从远程 pull docker image。
    if-not-present —— Runner 会首先检查本地是否有该 image，如果有则用本地的，如果没有则从远程拉取。
    never —— Runner 始终使用本地的 image。

  • Helper image

    当你使用 docker, docker+machine 或 kubernetes 作为 executor 时，GitLab Runner 将会使用特定的 container 来处理 Git、artifacts 和 cache 操作。通过在宿主机中键入以下命令：

    sudo docker images

    你会发现一些特殊的 images，如：

    REPOSITORY                          TAG
gitlab/gitlab-runner-helper     x86_64-3afdaba6
gitlab/gitlab-runner-helper     x86_64-cf91d5e1

    当然，你也可以通过配置 config.toml 里的 helper_image 字段来让 Runner 使用你自己定制化的 helper image。

想要了解更多关于 docker executor 的信息，请访问 docker executor。

常见问题

当在 Ubuntu18.04 上使用 docker executor runner 时，出现 Runner 无法连接网络的问题

这个是 Ubuntu18.04 与 Docker 的问题，是关于宿主机与 Container 的 DNS 的映射问题，详情可以访问 https://github.com/docker/lib…。
你的 pipeline 可能出现如下情况：

fatal: unable to access 'https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@code.siemens.com/zhen.xie/iavgitlabrunnertest.git/': Could not resolve host: code.siemens.com

该问题的解决办法是在 Runner 的配置文件 config.toml 里增加 dns = ["***.***.***.***"]，dns 的值你可以通过在宿主机上运行nmcli dev show 来获得。

Pipeline 出现 ”JAVA_HOME is not set and no java command could be found in your PATH”

这个错误通常出现在你使用 Shell executor 时，你可以在 GitLab page 上设置这个环境变量，具体路径是GitLab page -> Settings -> CI/CD -> Variables。

如何配置 GitLab Runner

请参考 https://docs.gitlab.com/runne…。

Runner 间隔多久去 GitLab 上检查是否有 job

config.toml文件的 check_interval 字段会决定这个时间间隔，它的默认值是 3 秒（注意当你把它设为 0 时依然采用的是默认值 3 秒，而不是 0 秒）。要解释它的意义，首先我们先来定义 worker，在config.toml 文件中定义了很多 runner，它们可能 executor 类型不同，可能注册地址不同，但都是由 GitLab Runner 这个服务来管理的，为了与 GitLab Runner 区分开，我们将 config.toml 文件中定义的 runner 称为 worker。对于不同的 worker，worker 之间（如 worker A —> worker B）的间隔为check_interval / worker_nums，但是对于 worker A 本身来说它下次去检查是否有 job 的时间间隔仍为check_interval。我们再举个简单例子：config.toml 定义了 3 个 worker—— worker A, worker B 和 worker C，check_interval 采用默认值为 3 秒，第 0 秒时 worker A 会去检查是否有属于自己的 job，第 1 秒时 worker B 会去检查，第 2 秒时 worker C 去检查，第 3 秒时 worker A 再检查……这个过程中 worker A 到 worker B 的间隔为 3 / 3 = 1 秒，而对于 worker A 下次检查 job 时的时间间隔为check_interval，即 3 秒。

官方文档对 check_interval 的解释：https://docs.gitlab.com/runne…。

config.toml里的 concurrent 字段的意义

concurrent限制了 整个 GitLab Runner能并发处理 job 的数量。特别注意 concurrent 与worker数量无任何关系，所有 worker 的工作是受 GitLab Runner 控制的，如果 concurrent 值为 1 并且有一个 worker 已经在工作了，那么即使其他 worker 达到了可以工作的条件也只能“pending”。

cache 存储在哪里

请参考 https://docs.gitlab.com/ee/ci…

怎样清除 cache

注意 cache 是没有过期时间的，而且每一次新的 push 触发的 pipeline，都会重新生成 cache，重新生成的 cache 的名字为“<cache-key>-<num>”，其中 num 是随着 push 数量递增的。如果不去清除 cache，cache 会永久保留在 Runner 上，日积月累会填满存储空间的，因此最好隔一段时间进行一次清除，清除方法请参考 https://docs.gitlab.com/ee/ci…，或者使用 clear_volumes.sh 这个简单脚本来处理它, 清除 cache 的原理是将相关的 volume 移除，当然，docker 也有自带的清除命令，推荐将 docker system prune -f --volumes 加入到定时任务中。

GitLab Runner 变量的优先级

请参考 https://docs.gitlab.com/ee/ci…

GitLab Runner 有哪些预定义的变量

请参考 https://docs.gitlab.com/ee/ci…

当我的 Runner 采用 docker 作为 executor 时，无法 build docker image

这是个“dind(docker in docker)”问题，一般 pipeline 会报如下错误：

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
time="2018-12-17T11:12:33Z" level=error msg="failed to dial gRPC: cannot connect to the Docker daemon. Is'docker daemon' running on this host?: dial unix

你可以将本地的 docker socket 绑定到 container 里来解决这个问题，具体方法是将 volumes = ["/var/run/docker.sock:/var/run/docker.sock"] 配置到 config.toml 文件里。

想要了解更多关于“dind”的信息，请参考 https://docs.gitlab.com/ee/ci…。

如何在 job 所对应的 container 里使用 git clone 命令

如果你想在 job 运行期间 clone 某些代码（如 shell 或 python 的脚本），首先要确保你的宿主机有权限 clone 代码，然后你就可以将你的 secret 挂载到 container 里，例如，你是通过 ssh 的方式克隆代码，并且你的 ssh 目录为 home/<user>/.ssh，你就可以在config.toml 文件里添加如下配置：

volumes = ["/home/x1twbm/.ssh:/root/.ssh:ro"]

然后，这个 job 所对应的 container 就可以拉取指定代码了。

退出移动版