GitLab Runner注册令牌复用与多实例多项目配置咨询

核心疑问解答 #

• 一个项目注册令牌可以注册多个Runner，并非只能绑定一个EC2实例。你遇到的“仅显示一个Runner”问题，通常是因为多次注册时使用了相同的--name参数，GitLab会将同名Runner视为同一实例，直接覆盖原有记录。
• 不需要为每个Runner单独生成令牌，同一项目/组/实例令牌可重复用于多台EC2的Runner注册。

正确的注册配置方式 #

1. 多Runner共享项目令牌的注册命令 #

注册时务必为每个Runner指定唯一名称（比如用EC2实例ID做后缀），示例命令：

gitlab-runner register \
  --url "https://your-gitlab-instance.com/" \
  --registration-token "PROJECT_REGISTRATION_TOKEN" \
  --name "runner-ec2-$(curl -s http://169.254.169.254/latest/meta-data/instance-id)" \
  --executor "shell" \
  --tag-list "ec2,shared-runner"

• --name通过EC2实例ID自动生成唯一标识，避免重复覆盖
• --tag-list设置统一标签，方便后续项目通过标签精准调用Runner

2. 实现同一组Runner关联多个项目 #

推荐两种更易维护的方案，替代给每个项目单独注册的繁琐操作：

方案一：使用GitLab组级注册令牌

• 生成路径：进入GitLab组的「设置」→「CI/CD」→「Runners」，获取组注册令牌
• 注册后，Runner会自动关联组内所有项目（包含后续新增项目）
• 注册时同样需指定唯一名称和统一标签

方案二：使用实例级（共享）Runner

• 生成路径：进入GitLab实例的「管理中心」→「Runners」→「注册一个实例Runner」获取令牌
• 注册的Runner会成为全实例共享资源，所有项目均可使用（需项目开启「允许共享Runner」）
• 适合跨多个组/项目的通用Runner集群

最佳实践总结 #

• 令牌复用原则：同一项目/组/实例令牌可注册任意数量Runner，核心是保证每个Runner名称唯一
• 标签化管理：给Runner设置业务场景标签（如backend, frontend, build），项目通过.gitlab-ci.yml中的tags字段指定调用对应Runner，实现灵活映射
• 权限最小化：优先使用组级令牌而非实例级令牌，避免过度授权；项目级令牌仅用于专属项目的Runner
• 自动化注册：在EC2实例启动脚本中嵌入注册命令，结合实例ID自动生成唯一Runner名称，实现Runner集群的自动化部署与注册

内容的提问来源于stack exchange，提问作者Goural