症状
本篇指南处理“GitLab CI 任务卡住 — 没有匹配标签的 Runner”。请从症状出发，按顺序执行诊断，在推进前确认每个假设；随后通过修复与验证步骤闭环。
可观察到的症状包括：
- 流水线任务显示 “This job is stuck because you don’t have any active runners”
- 带特定标签的任务从不启动，未加标签的可用
- 卡住的任务在整个超时期间保持 pending
诊断
先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。
步骤 1
grep -n "tags:" .gitlab-ci.yml; gitlab-runner list若无 runner 声明该任务标签，任务就永远不会被拾取。
步骤 2
Admin → Runners → filter by tag and status即便标签匹配，离线或暂停的 runner 也会导致任务卡住。
常见诱因（按出现频率排序）：
- 任务标签与任何已注册 runner 的标签都不匹配
- 匹配的 runner 全部离线、暂停或已达容量
- 项目禁用了共享 runner
根因
GitLab 只会把任务调度到宣告了任务所需的全部标签的 runner 上。某标签无匹配 runner 时，任务会保持 pending 直到超时（“卡住”），因为没有可用的 runner。
修复
让任务与 runner 的标签对齐，注册带所需标签的 runner，确保匹配的 runner 在线且未暂停，并移除任务中不必要的标签。
注意：使用仅存在于临时 runner 上的标签，会在其缩容时使流水线不稳定；应记录 runner 集群要求。
stages: [build]
build:
stage: build
tags:
- docker # every eligible runner must advertise this tag
- linux
script:
- make build
# check registered runners and their tags
# gitlab-runner list
# gitlab-runner verify验证
重跑流水线并确认任务被匹配的 runner 拾取并完成；验证该 runner 的最近构建中出现该任务。
修复后补充一条回归测试，复现原始症状，防止问题再次出现。
这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。