部署ARC Runner至GitHub组织后未关联的问题求助

一、前置准备 #

• 确认用于ARC Runner的GitHub App已安装到目标组织，并开启以下权限：
  • administration:write（用于管理Runner资源）
  • actions:write（用于操作Actions相关配置）
• 准备好三类核心凭证：GitHub App ID、组织级安装ID、GitHub App私钥（PEM格式原文件）
• 确保kubectl已配置集群访问权限，且目标Kubernetes命名空间已创建（示例命名空间：arc-runners）

二、创建凭证Secret #

在目标命名空间下创建存储GitHub App凭证的Secret：

kubectl create secret generic arc-runner-secrets \
  --namespace arc-runners \
  --from-literal=github_app_id=<你的App ID> \
  --from-literal=github_app_installation_id=<组织安装ID> \
  --from-file=github_app_private_key=<你的私钥文件路径>

注意：私钥直接使用GitHub生成的PEM文件，不要修改文件内的格式或内容

三、Helm部署（推荐方案） #

1. 添加ARC Runner Helm仓库并更新：

helm repo add actions-runner-controller https://actions-runner-controller.github.io/actions-runner-controller
helm repo update

2. 执行组织级Runner部署：

helm install arc-runner-set actions-runner-controller/actions-runner-controller \
  --namespace arc-runners \
  --set=authSecret.name=arc-runner-secrets \
  --set=githubUrl=https://github.com \
  --set=runnerGroup=<组织内Runner组名称，如"arc-managed-group"> \
  --set=repository= \
  --set=organization=<你的组织名称>

关键参数说明：

• organization：必填，填写目标GitHub组织的名称
• repository：留空，明确为组织级部署而非仓库级
• runnerGroup：指定Runner要加入的组织内分组，若分组不存在会自动创建

四、kubectl YAML部署方案 #

创建runner-deployment.yaml配置文件：

apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
  name: arc-org-runner
  namespace: arc-runners
spec:
  replicas: 2
  template:
    spec:
      organization: <你的组织名称>
      runnerGroup: <组织Runner组名称>
      githubApiUrl: https://api.github.com
      githubAppSecret:
        name: arc-runner-secrets

执行部署命令：

kubectl apply -f runner-deployment.yaml

五、验证与排查 #

1. 检查Kubernetes资源状态：

kubectl get runnerdeployments -n arc-runners
kubectl get runners -n arc-runners

2. 登录GitHub组织后台，进入Settings > Actions > Runners，查看Runner列表是否出现部署的实例

3. 常见问题排查：

   • 若Runner未显示，查看Pod日志定位错误：

     kubectl logs -n arc-runners <runner-pod名称>
     

   • 核对Secret内的凭证：安装ID必须是组织级而非仓库级，私钥内容无篡改
   • 确认GitHub App的权限已正确授予，且安装状态为"已安装"到目标组织

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