Gitlab Runner注册与配置：解决CICD Pipelines Pending状态的实战指南

1. 为什么你的Pipeline总是卡在Pending状态？

每次提交代码后，最让人抓狂的就是看到Pipeline状态一直显示为Pending。这种情况我遇到过太多次了，特别是在使用Shell执行器的Java项目中。Pending状态本质上表示GitLab知道有这个构建任务，但是找不到可用的Runner来执行它。

造成Pending的常见原因主要有三个：Runner未正确注册、标签不匹配、Runner本身没有正常运行。我曾经接手过一个项目，团队花了三天时间排查Pipeline卡住的问题，最后发现只是因为Runner的标签设置错误。这种问题看似简单，但确实困扰过很多开发者。

2. 彻底删除有问题的Runner

遇到Pending问题时，我建议先清理可能有问题的旧Runner。很多开发者不知道的是，GitLab Runner的配置信息会同时保存在GitLab服务器和本地机器上。仅仅在网页端删除是不够的，需要在服务器上执行以下命令：

gitlab-runner verify --delete --name Runner名称

这个命令做了两件事：首先验证Runner的状态，然后彻底删除它。我建议在删除前先用gitlab-runner list查看当前注册的所有Runner信息。有一次我发现一个项目里竟然注册了5个同名Runner，这就是导致冲突的根源。

删除后，最好也检查下GitLab的配置文件，通常位于/etc/gitlab-runner/config.toml。有时候配置残留也会导致问题，我习惯直接备份后清空这个文件。

3. 手把手注册新Runner

注册新Runner时，有几个关键参数需要特别注意。以下是我在Java项目中最常用的注册流程：

gitlab-ci-multi-runner register

接下来会进入交互式配置，这几个选项特别重要：

1. Coordinator URL：填写你的GitLab实例地址，比如http://gitlab.example.com/
2. Registration Token：从项目的Settings > CI/CD > Runners页面获取
3. Description：建议使用项目名-环境的格式，比如order-service-prod
4. Tags：Java项目我强烈建议使用p_jdk8或p_jdk11这样的标签
5. Executor：Java项目选择shell最方便

这是我的一个真实配置示例：

Please enter the gitlab-ci coordinator URL: http://192.168.175.100/ Please enter the gitlab-ci token for this runner: QGzw5t_y8w6gfHzKdbwS Please enter the gitlab-ci description for this runner: order-service-runner Please enter the gitlab-ci tags for this runner (comma separated): p_jdk8 Whether to run untagged builds [true/false]: false Whether to lock Runner to current project [true/false]: false Please enter the executor: shell

特别注意run untagged builds选项，对于Java项目我建议设为false，这样可以避免非Java任务占用这个Runner。

4. Shell执行器的Java项目特殊配置

选择shell执行器后，还需要针对Java项目做一些额外配置。首先确保服务器上已经安装了正确版本的JDK。我遇到过因为JAVA_HOME设置不正确导致构建失败的情况。

检查JDK安装的一个小技巧：

which java java -version

然后在项目的.gitlab-ci.yml中，建议添加before_script来设置环境变量：

before_script: - export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64 - export PATH=$JAVA_HOME/bin:$PATH

对于Maven项目，还需要配置settings.xml的位置。我习惯把这些配置放在Runner的预执行脚本中：

echo "配置Maven镜像..." mkdir -p ~/.m2 cat > ~/.m2/settings.xml <<EOF <settings> <mirrors> <mirror> <id>aliyun</id> <name>Aliyun Maven</name> <url>https://maven.aliyun.com/repository/public</url> <mirrorOf>central</mirrorOf> </mirror> </mirrors> </settings> EOF

5. 标签系统的正确使用姿势

标签匹配是导致Pending的常见原因。GitLab的标签系统有几个容易踩的坑：

1. 标签命名：建议使用p_前缀表示项目专用，比如p_jdk8
2. 多标签使用：可以用逗号分隔多个标签，如p_jdk8,p_redis
3. .gitlab-ci.yml配置：必须确保job的tags与Runner的标签匹配

build: stage: build tags: - p_jdk8 script: - mvn clean package

我曾经遇到过一个典型问题：Runner注册时标签设为jdk8，但CI文件里写的是java8，这种大小写和拼写差异会导致匹配失败。建议团队内部统一标签命名规范。

6. Runner日常维护技巧

Runner正常运行后，还需要定期维护。这几个命令我每周都会用到：

检查Runner状态：

gitlab-runner status

查看正在执行的Job：

gitlab-runner list

重启Runner服务：

gitlab-runner restart

对于生产环境，我建议设置监控，当Runner离线时能及时报警。可以写个简单的定时任务：

*/5 * * * * if [ $(gitlab-runner status | grep -c "running") -eq 0 ]; then echo "Runner down" | mail -s "GitLab Runner Alert" admin@example.com; fi

日志检查也很重要，Runner的日志通常位于：

tail -f /var/log/gitlab-runner.log

7. 高级排查技巧

当Pipeline还是卡在Pending时，可以尝试这些高级排查方法：

1. 检查Runner的并发设置： 修改/etc/gitlab-runner/config.toml中的concurrent值

2. 查看GitLab的Sidekiq队列： 如果使用自建GitLab，可以检查Sidekiq是否积压

   sudo gitlab-rails console Sidekiq::Queue.new.size

3. Runner的调试模式： 停止Runner服务后，用调试模式启动：

   gitlab-runner run --debug

4. 网络连接测试： 确保Runner能访问GitLab服务器：

   curl -I http://gitlab.example.com

我最近遇到一个棘手问题：Runner能注册成功，但总是Pending。最后发现是公司的网络策略阻止了Runner与GitLab的反向API调用。通过在Runner服务器上设置代理解决了这个问题（注：此处不涉及任何敏感网络技术）。

8. 容器化环境下的特殊考量

虽然本文主要讲Shell执行器，但提一下容器化环境下的注意事项。如果你使用Docker执行器，Java项目需要特别注意：

1. 镜像选择：使用官方maven镜像时注意版本

   image: maven:3.6.3-jdk-8

2. 卷挂载：缓存.m2目录加速构建

   volumes: - "$HOME/.m2:/root/.m2"

3. 资源限制：Java应用需要更多内存

   services: - name: docker:dind command: ["--storage-driver=overlay2", "--mtu=1500", "--registry-mirror=https://registry.example.com"]

这些配置虽然与Shell执行器不同，但原理相通：确保环境一致性和构建效率。