GitLab Runner 入门及常见问题

安装GitLab Runner

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

  1. 运行以下命令增加GitLab官方仓库:
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
  1. 安装最新版本的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
  1. 输入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,当然前提条件是你有权限进入这些页面。

RegisterRunner.PNG

  1. 输入你的注册token:
Please enter the gitlab-ci token for this runner  
xxx

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

  1. 输入对这个Runner的表述(同时也是这个Runner的名字),当然,你也可以稍后在GitLab page上修改它:
Please enter the gitlab-ci description for this runner  
[hostame] my-runner
  1. 输入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。

  1. 输入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>
    
    1. 启动服务:
    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_dircache_dir指向的均是container里的目录,要想将container里的数据持久化,需要用到volumes字段,这个字段的使用和docker volume的使用是类似的,只需在config.toml[runner.docker]部分添加volumes = ["/cache", "<host_dir:container_dir>:rw"]即可实现container里/cache目录数据的永久保存以及将host目录挂载到相应的container目录并具有读写的功能。

  • Pull policies

    当你使用dockerdocker+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+machinekubernetes作为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/libnetwork/issues/2187
你的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/runner/configuration/advanced-configuration.html#the-global-section

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/runner/configuration/advanced-configuration.html#how-check_interval-works

config.toml里的concurrent字段的意义

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

cache存储在哪里

请参考https://docs.gitlab.com/ee/ci/caching/#where-the-caches-are-stored

怎样清除cache

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

GitLab Runner 变量的优先级

请参考https://docs.gitlab.com/ee/ci/variables/#priority-of-environment-variables

GitLab Runner有哪些预定义的变量

请参考https://docs.gitlab.com/ee/ci/variables/#predefined-variables-environment-variables

当我的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/docker/using_docker_build.html#use-docker-in-docker-executor

如何在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就可以拉取指定代码了。

推荐阅读更多精彩内容

  • 一、持续集成(Continuous Integration) 要了解GitLab-CI与GitLab Runner...
    tsyeyuanfeng阅读 96,032评论 18 134
  • 目录持续集成&持续集成工具的介绍gitlab-ci runner的基本配置方法(mac版本) 持续集成 CI,Co...
    骆天涯阅读 40,092评论 7 25
  • 这是阿里内网的一篇文章,感有用,故转载来了,自己实际搭建了,故记录一下: 背景在日常工作中,我们往往会搭建基于je...
    新强吖阅读 5,684评论 0 4
  • 捉奸记 《两晋演义》第二回主说贾充家事,第一部分是丑女配蠢儿,是为政治联姻;第二部分则是幼女私佩幕宾,乃败家风的奸...
    平凡的爱好阅读 286评论 0 3
  • 还记得一起河边柳枝编花环 还记得一起白雪地头弄红梅 不要叹物是人非事事休 只想与你再恋一回 野菊花的花环是你送我的...
    香辣豌豆阅读 348评论 0 1
  • 祭奠 /西贝 一支忧郁的风一丝笑靥不带 落寞降临浮动三缕尘埃 尘埃落定便把青春牢牢覆盖 没有来得及涂鸦的只能腐蚀成...
    JK不带罗琳阅读 190评论 2 1
  • 广告佳作是不引公众注意它自己就把产品推销掉的佳作。 真正决定消费者购买或不购买的是你的广告的内容,而不是它的形式。...
    暮青在人间阅读 153评论 0 0