Linux 部署 GitLab Runner

一、安装 GitLab Runner

1. 下载安装包（根据系统架构选择）

# 对于 x86_64 系统
sudocurl-L--output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64

# 对于 ARM64 系统
sudocurl-L--output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-arm64

2. 设置执行权限

sudochmod+x /usr/local/bin/gitlab-runner

3. 创建 GitLab Runner 用户

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

4. 安装并作为服务运行

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

5. 使用包管理器安装（推荐）

Debian/Ubuntu:

# 添加 GitLab 官方仓库
curl-L"https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudobash

# 安装最新版本
sudo apt-get install gitlab-runner

# 安装特定版本
sudo apt-get install gitlab-runner=16.5.0

RHEL/CentOS/Fedora:

# 添加 GitLab 官方仓库
curl-L"https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh" | sudobash

# 安装
sudo yum install gitlab-runner

# 对于 CentOS 8/RHEL 8
sudo dnf install gitlab-runner

二、注册 GitLab Runner

在 GitLab 项目中：

1. 进入项目 → Settings → CI/CD → Runners
2. 展开 "Set up a specific Runner manually"
3. 获取以下信息：
- URL：GitLab 实例地址
- Registration token：注册令牌

2. 注册 Runner

sudo gitlab-runner register

交互式注册过程：

Enter the GitLab instance URL: https://gitlab.com
Enter the registration token: GR1348941nKpxy9BocH2oyjzC2oX
Enter a description for the runner: my-runner
Enter tags for the runner (comma separated): linux,docker
Enter optional maintenance note for the runner: 
Enter an executor: docker
Enter the default Docker image: alpine:latest

3. 非交互式注册

sudo gitlab-runner register \
--non-interactive \
--url"https://gitlab.com" \
--registration-token"GR1348941nKpxy9BocH2oyjzC2oX" \
--executor"docker" \
--docker-image"alpine:latest" \
--description"docker-runner" \
--tag-list"docker,linux" \
--run-untagged="true" \
--locked="false"

三、常用命令

服务管理命令

# 启动服务
sudo gitlab-runner start

# 停止服务
sudo gitlab-runner stop

# 重启服务
sudo gitlab-runner restart

# 查看状态
sudo gitlab-runner status

# 检查运行状态
sudo gitlab-runner verify

# 查看版本
gitlab-runner --version

Runner 管理命令

# 列出所有 Runner
sudo gitlab-runner list

# 查看 Runner 详情
sudo gitlab-runner verify --delete

# 重启 Runner
sudo gitlab-runner restart

# 停止 Runner
sudo gitlab-runner stop

# 检查 Runner 配置
sudo gitlab-runner verify

注册和管理

# 注册新 Runner
sudo gitlab-runner register

# 注销 Runner
sudo gitlab-runner unregister --url https://gitlab.com --token TOKEN

# 注销指定 Runner
sudo gitlab-runner unregister --name"runner-name"

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

配置相关

# 检查配置文件语法
sudo gitlab-runner verify

# 编辑配置文件
sudovi /etc/gitlab-runner/config.toml

# 查看配置
sudocat /etc/gitlab-runner/config.toml

四、配置文件说明

配置文件位置：/etc/gitlab-runner/config.toml

示例配置

concurrent =4
check_interval =0

[session_server]
  session_timeout =1800

[[runners]]
  name ="my-runner"
  url ="https://gitlab.com"
  token ="TOKEN"
  executor ="docker"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.docker]
    tls_verify =false
    image ="alpine:latest"
    privileged =false
    disable_entrypoint_overwrite =false
    oom_kill_disable =false
    disable_cache =false
    volumes = ["/cache"]
    shm_size =0

五、Docker Executor 配置

1. 安装 Docker

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker.io
sudo systemctl enable docker
sudo systemctl start docker

# 添加用户到 docker 组
sudo usermod -aG docker gitlab-runner

2. Docker Executor 配置示例

[[runners]]
  name ="docker-runner"
  url ="https://gitlab.com"
  token ="TOKEN"
  executor ="docker"
  [runners.docker]
    image ="alpine:latest"
    privileged =true
    disable_cache =false
    volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock"]
    shm_size =0

六、Shell Executor 配置

1. 配置 Shell Executor

[[runners]]
  name ="shell-runner"
  url ="https://gitlab.com"
  token ="TOKEN"
  executor ="shell"
  shell ="bash"
  [runners.custom_build_dir]

2. 设置权限

# 允许 gitlab-runner 用户使用 sudo 无需密码
sudo visudo
# 添加以下内容：
gitlab-runner ALL=(ALL) NOPASSWD: ALL

七、故障排查

查看日志

# 查看 Runner 日志
sudo gitlab-runner --debug run

# 查看系统服务日志
sudo journalctl -u gitlab-runner -f

# 查看详细日志
sudo tail -f /var/log/gitlab-runner/gitlab-runner.log

八、高级配置

设置并发数

concurrent = 4

配置缓存

[runners.cache]
  Type ="s3"
  Path ="gitlab-runner"
  Shared =false
  [runners.cache.s3]
    ServerAddress ="s3.amazonaws.com"
    AccessKey ="access-key"
    SecretKey ="secret-key"
    BucketName ="gitlab-runner-cache"
    BucketLocation ="us-east-1"

配置自定义环境变量

# 在 /etc/gitlab-runner/config.toml 中添加
environment = ["PATH=/usr/local/bin:/usr/bin:/bin", "CUSTOM_ENV=value"]

九、卸载 GitLab Runner

# 停止服务
sudo gitlab-runner stop

# 卸载服务
sudo gitlab-runner uninstall

# 删除文件
sudorm-f /usr/local/bin/gitlab-runner
sudorm-rf /etc/gitlab-runner
sudorm-rf /home/gitlab-runner

# 删除用户
sudo userdel -r gitlab-runner

十、Docker 方式部署（替代方案）

# 使用 Docker 运行 GitLab Runner
docker run -d \
--name gitlab-runner \
--restart always \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /srv/gitlab-runner/config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

# 在容器内注册 Runner
docker exec -it gitlab-runner gitlab-runner register \
--non-interactive \
--url"https://gitlab.com" \
--registration-token"TOKEN" \
--executor"docker" \
--docker-image"alpine:latest" \
--description"docker-container-runner"