criscolosimo04/simply-github-runner-selfhosted

镜像概述

自托管GitHub Runner镜像，专为在Kubernetes（K8s）集群环境中执行CI/CD任务设计。该镜像集成了GitHub Runner核心组件及与K8s集群交互所需的工具（如kubectl），可直接在K8s集群内部或外部部署，简化需要访问集群资源的自动化流程配置。

核心功能和特性

• 预配置GitHub Runner：内置GitHub Runner核心组件，无需手动安装即可注册到GitHub仓库/组织
• K8s工具集成：包含kubectl等K8s客户端工具，支持直接与K8s集群交互（资源管理、状态检查、应用部署等）
• 灵活部署：支持在K8s集群内部（如作为Pod部署）或外部环境运行，适配不同基础设施需求
• 轻量级设计：基于精简基础镜像构建，减少资源占用，适合容器化环境部署
• 易于扩展：支持通过环境变量或挂载配置文件自定义Runner行为及K8s工具配置

使用场景和适用范围

• K8s集成CI/CD流水线：需在自动化流程中执行K8s相关操作（如部署应用到集群、更新ConfigMap、检查Pod状态）
• 自托管Runner环境：企业或团队使用自托管GitHub Runner时，需直接访问K8s集群资源的场景
• 私有部署环境：在防火墙隔离或私有网络环境中，需要同时运行GitHub Runner和与内部K8s集群交互的场景
• 多集群管理：需通过Runner统一管理多个K8s集群资源的自动化任务场景

使用方法和配置说明

环境变量配置

启动容器前需配置以下必要环境变量：

Docker部署示例

基本运行命令（外部环境）

bash
docker run -d \
  -e GITHUB_REPOSITORY="owner/repo" \
  -e RUNNER_TOKEN="your_runner_token" \
  -e RUNNER_NAME="k8s-runner-01" \
  -e RUNNER_LABELS="k8s,ci" \
  -v /path/to/local/kubeconfig:/root/.kube/config \  # 挂载本地kubeconfig以访问K8s集群
  --name github-runner-k8s \
  [镜像名称]

在K8s集群内部署（作为Pod）

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: github-runner-k8s
  namespace: ci-cd
spec:
  replicas: 1
  selector:
    matchLabels:
      app: github-runner-k8s
  template:
    metadata:
      labels:
        app: github-runner-k8s
    spec:
      serviceAccountName: runner-sa  # 需提前创建具有适当权限的ServiceAccount
      containers:
      - name: runner
        image: [镜像名称]
        env:
        - name: GITHUB_REPOSITORY
          value: "owner/repo"
        - name: RUNNER_TOKEN
          valueFrom:
            secretKeyRef:
              name: runner-secrets
              key: runner-token
        - name: RUNNER_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: RUNNER_LABELS
          value: "k8s,ci,cluster-internal"

注意事项

1. Runner令牌有效期：RUNNER_TOKEN为临时令牌，有效期通常为1小时，生产环境建议通过GitHub App或长期令牌机制自动获取
2. K8s权限控制：集群内部署时，需为Runner Pod关联适当权限的ServiceAccount，遵循最小权限原则
3. 持久化配置：如需保留Runner配置（如证书、缓存），可挂载持久卷到/home/runner/_work目录
4. 网络访问：确保Runner容器可访问GitHub API（api.github.com）及目标K8s集群API Server