Kubernetes部署的Gitlab Runner运行CI任务报凭证未授权错误如何解决

触发的错误信息如下：

ERROR: Job failed (system failure): prepare environment: setting up credentials: Unauthorized. Check https://docs.gitlab.com/runner/shells/index.html#shell-profile-loading for more information

报错截图：

根因说明 #

该错误出现在自有Kubernetes集群部署的Gitlab Runner执行CI任务时，核心原因是Runner缺少Kubernetes集群的RBAC操作权限，无法在任务初始化阶段拉取凭证、创建任务Pod。仅配置Runner注册token、未配置对应集群访问权限是问题的直接诱因。

修复步骤 #

• 第一步：补充Gitlab Runner对应RBAC权限配置
  在Runner部署的命名空间下创建如下RBAC资源：

# ServiceAccount配置
apiVersion: v1
kind: ServiceAccount
metadata:
  name: gitlab-runner-sa
  namespace: <替换为你部署Runner的命名空间>
---
# ClusterRole配置
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: gitlab-runner-clusterrole
rules:
- apiGroups: [""]
  resources: ["pods", "pods/exec", "secrets", "configmaps"]
  verbs: ["get", "list", "watch", "create", "patch", "delete"]
- apiGroups: [""]
  resources: ["events"]
  verbs: ["list", "watch"]
---
# ClusterRoleBinding配置
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: gitlab-runner-clusterrolebinding
subjects:
- kind: ServiceAccount
  name: gitlab-runner-sa
  namespace: <替换为你部署Runner的命名空间>
roleRef:
  kind: ClusterRole
  name: gitlab-runner-clusterrole
  apiGroup: rbac.authorization.k8s.io

创建完成后执行kubectl apply -f <上述配置文件名>生效。

• 第二步：绑定ServiceAccount到Gitlab Runner部署
  修改Gitlab Runner的Deployment配置，在spec.template.spec层级添加serviceAccountName配置，关联上面创建的ServiceAccount：

spec:
  template:
    spec:
      serviceAccountName: gitlab-runner-sa
      # 其他原有配置保持不变

更新Deployment后重启Runner Pod。

• 第三步：校验Runner执行器配置
  确认Runner的config.toml配置中[runners.kubernetes]字段下没有手动填写错误的bearer_token、certificate_authority等集群认证参数，留空状态下Runner会自动读取关联ServiceAccount的认证信息，无需额外配置。如果之前填写了错误的认证参数，删除对应配置后重启Runner即可。

• 第四步：验证修复结果
  重新触发CI任务，确认Runner可以正常拉起任务Pod执行流水线。

• 额外排查点：版本兼容性校验
  完成上述配置后如果仍报错，确认你部署的Gitlab Runner大版本和Gitlab实例大版本差不超过1个小版本，同时确认Runner版本兼容当前Kubernetes集群版本，避免跨大版本导致的认证逻辑不兼容问题。

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