1. 简介
- 1.1 Runner 类型
- 1.2 Runner 状态
2. 安装 Runner
- 2.1 包管理器安装
  - 2.1.1 添加官方仓库
For Debian/Ubuntu/Mint
For RHEL/CentOS/Fedora
- 2.1.3 安装指定版本
- 2.1.4 升级版本
2.2 rpm 或 deb 包安装
- 2.2.1 Debian 或 Ubuntu
- 2.2.2 CentOS 或 Red Hat
2.3 二进制安装
3. 注册 Runner
4. gitlab-runner 命令行工具的使用
- 4.1 查看帮助
- 4.2 常用命令
5. runner 配置
- 5.1 runner 本地配置
- 5.2 gitlab server 配置

1. 简介

GitLab Runner 是一个独立的开源项目，使用 Go 语言编写，可以在 Linux、macOS 和 Windows 等操作系统上运行，用于运行 CI/CD 作业并将结果发送回 GitLab。

1.1 Runner 类型

shared：运行整个平台项目的作业（gitlab）
group：运行特定 group 下的所有项目的作业（group）
specific: 运行指定的项目作业（project）

1.2 Runner 状态
locked：无法运行项目作业
paused：不会运行作业
2. 安装 Runner
官方文档
2.1 包管理器安装
2.1.1 添加官方仓库
```bash
For Debian/Ubuntu/Mint
curl -L “https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh“ | sudo bash

For RHEL/CentOS/Fedora

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

<a name="igYiU"></a>
### 2.1.2 安装最新版本
```bash
# For Debian/Ubuntu/Mint
sudo apt-get install gitlab-runner
# For RHEL/CentOS/Fedora
sudo yum install gitlab-runner

2.1.3 安装指定版本

# for DEB based systems
apt-cache madison gitlab-runner
sudo apt-get install gitlab-runner=10.0.0
# for RPM based systems
yum list gitlab-runner --showduplicates | sort -r
sudo yum install gitlab-runner-10.0.0-1

2.1.4 升级版本

# For Debian/Ubuntu/Mint
sudo apt-get update
sudo apt-get install gitlab-runner
# For RHEL/CentOS/Fedora
sudo yum update
sudo yum install gitlab-runner

2.2 rpm 或 deb 包安装

清华源下载地址
选择一个版本并下载相应的包文件。

2.2.1 Debian 或 Ubuntu

dpkg -i gitlab-runner_<arch>.deb

2.2.2 CentOS 或 Red Hat

rpm -ivh gitlab-runner_<arch>.rpm

2.3 二进制安装

2.3.1 下载二进制安装包

# Linux x86-64
sudo curl -L --output /usr/local/bin/gitlab-runner "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64"

2.3.2 添加执行权限

sudo chmod +x /usr/local/bin/gitlab-runner

2.3.3 创建用户

sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

2.3.4 安装并运行

sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

2.3.5 升级版本

# 停止服务
sudo gitlab-runner stop
# 下载最新安装包
sudo curl -L --output /usr/local/bin/gitlab-runner "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64"
# 添加执行权限并启动
sudo chmod +x /usr/local/bin/gitlab-runner
sudo gitlab-runner start

3. 注册 Runner

3.1 获取 token

不同类型的 runner token 存放位置不一样。

3.1.1 shared 类型

shared 类型 token 位于 Admin -> Overview -> runner ：
shared类型token.jpg

3.1.2 group 类型

group 类型 token 位于 group -> Settings -> CI/CD -> Runners -> Group Runners：
group类型-token.jpg

3.1.3 specific 类型

specific 类型 token 位于 project -> Settings -> CI/CD -> Runners -> Group Runners：
specific类型-token.jpg

3.2 交互式注册

使用 gitlab-runner register命令交互式注册 runner。

[root@U20-03:~]# gitlab-runner register
Runtime platform                                    arch=amd64 os=linux pid=8022 revision=8925d9a0 version=14.1.0
Running in system-mode.
# 输入GitLab实例的URL。
Enter the GitLab instance URL (for example, https://gitlab.com/):
http://gitlab.wuvikr.top
# 输入 runner 的注册 token。
Enter the registration token:
_Q8rxkjuzmV2-G4N9Puy
# 输入 runner 的描述信息
Enter a description for the runner:
[U20-03.wuvikr.top]: devops-shared-runner
# 输入 runner 的选择标签，多个标签用逗号隔开。
Enter tags for the runner (comma-separated):
build,java
Registering runner... succeeded                     runner=_Q8rxkju
# 选择 runner 的执行器类型。
Enter an executor: shell, ssh, virtualbox, docker+machine, docker-ssh+machine, kubernetes, custom, docker, docker-ssh, parallels:
shell
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

3.3 非交互式注册

[root@U20-03:~]# gitlab-runner register \
--non-interactive \
--url "http://gitlab.wuvikr.top" \
--registration-token "_Q8rxkjuzmV2-G4N9Puy" \
--executor "shell" \
--description "sharedrunner" \
--tag-list "build,k8s,go" \
--run-untagged="true" \
--locked="false" \
--access-level="not_protected"

注册完成后，可以在 gitlab admin -> Overview -> runner 页面查看到 runner 信息。
gitlab-runner信息.jpg

4. gitlab-runner 命令行工具的使用

4.1 查看帮助

[root@U20-03:~]# gitlab-runner --help
NAME:
   gitlab-runner - a GitLab Runner

USAGE:
   gitlab-runner [global options] command [command options] [arguments...]

VERSION:
   14.1.0 (8925d9a0)

AUTHOR:
   GitLab Inc. <support@gitlab.com>

COMMANDS:
     exec                  execute a build locally
     list                  List all configured runners
     run                   run multi runner service
     register              register a new runner
     install               install service
     uninstall             uninstall service
     start                 start service
     stop                  stop service
     restart               restart service
     status                get status of a service
     run-single            start single runner
     unregister            unregister specific runner
     verify                verify all registered runners
     artifacts-downloader  download and extract build artifacts (internal)
     artifacts-uploader    create and upload build artifacts (internal)
     cache-archiver        create and upload cache artifacts (internal)
     cache-extractor       download and extract cache artifacts (internal)
     cache-init            changed permissions for cache paths (internal)
     health-check          check health for a specific address
     read-logs             reads job logs from a file, used by kubernetes executor (internal)
     help, h               Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --cpuprofile value           write cpu profile to file [$CPU_PROFILE]
   --debug                      debug mode [$DEBUG]
   --log-format value           Choose log format (options: runner, text, json) [$LOG_FORMAT]
   --log-level value, -l value  Log level (options: debug, info, warn, error, fatal, panic) [$LOG_LEVEL]
   --help, -h                   show help
   --version, -v                print the version

gitlab-runner COMMANDS --help 可以查看更详细的帮助说明：

[root@U20-03:~]# gitlab-runner list --help
Runtime platform                                    arch=amd64 os=linux pid=18603 revision=8925d9a0 version=14.1.0
NAME:
   gitlab-runner list - List all configured runners

USAGE:
   gitlab-runner list [command options] [arguments...]

OPTIONS:
   -c value, --config value  Config file (default: "/etc/gitlab-runner/config.toml") [$CONFIG_FILE]

4.2 常用命令

gitlab-runner register        # runner 注册
gitlab-runner list                # 列出保存在配置文件中的所有 runner
gitlab-runner verify            # 检查注册的 runner 是否可以连接
gitlab-runner unregister    # 取消已注册的 runner。
gitlab-runner start                # 启动 runner
gitlab-runner stop                # 停止 runner
gitlab-runner restart            # 重启 runner

#使用令牌注销
gitlab-runner unregister --url http://gitlab.example.com/ --token t0k3n

#使用名称注销（同名删除第一个）
gitlab-runner unregister --name test-runner

#注销所有
gitlab-runner unregister --all-runners

5. runner 配置

5.1 runner 本地配置

gitlab-runner 启动时，默认会使用 —config 选项加载 /etc/gitlab-runner/config.toml配置文件，打开配置文件查看一下：

[root@U20-03:gitlab-runner]# cat /etc/gitlab-runner/config.toml
concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "sharedrunner"
  url = "http://gitlab.wuvikr.top"
  token = "TnHxDszfyTwFDDtxeHNL"
  executor = "shell"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]

可以看到，注册的 runner 信息也被存储在此配置文件中。另外还有一些其他参数可以设置，具体可以参考官方文档。
GitLab Runner 每 3 秒检查一次配置修改，并在必要时自动重新加载配置，另外也会响应 SIGHUP 信号来重载配置。

5.2 gitlab server 配置

runner 注册后，可以在 gitlab 上查看并编辑配置 runner：
编辑runner.jpg
编辑runner02.jpg
注意：这里的配置是 gitlab 中的配置，与 runner 本地的配置无关。

GitLab Runner