github/k8s-actions-runner

Self Hosted Actions Runner On K8s 技术文档

1. 概述

1.1 镜像概述

self-hosted-k8s-runner 是一个在 Kubernetes 集群中部署自托管 GitHub Actions Runner 的解决方案，旨在提供灵活、可扩展的工作流执行环境。该方案通过容器化方式运行 GitHub Actions Runner，结合 Kubernetes 的编排能力，实现 runners 的动态管理、自动扩缩容及生命周期控制，适用于需要自定义执行环境或对资源、网络有特定要求的场景。

2. 核心功能和特性

2.1 核心功能

• 动态扩缩容：根据 GitHub Actions 工作流队列长度自动调整 runner 数量，优化资源利用率。
• 自动注册/注销：runner 启动时自动向 GitHub 注册，停止时自动注销，避免无效 runner 残留。
• 生命周期管理：支持一次性 runner（完成任务后销毁）或持久化 runner，满足不同工作流需求。
• 环境隔离：通过 Kubernetes Pod 实现 runner 间的资源隔离，避免工作流相互干扰。

2.2 关键特性

• GitHub 集成：支持组织、仓库或企业级别的 runner 注册，适配私有/公共仓库。
• 资源控制：可配置 CPU、内存、GPU 等资源限制，适配计算密集型任务。
• 安全增强：通过 Kubernetes Secret 管理敏感信息（如 GitHub Token），支持 RBAC 权限控制。
• 配置灵活：支持自定义 runner 标签、工作目录、网络代理及环境变量注入。

3. 使用场景和适用范围

3.1 适用场景

• 自定义执行环境：需预装特定工具（如 SDK、数据库、GPU 驱动）的工作流。
• 资源密集型任务：如 CI/CD 构建、机器学习训练、大数据处理等需高 CPU/内存/GPU 的场景。
• 网络隔离需求：工作流需访问内部私有服务（如数据库、API）或受防火墙限制的资源。
• 成本优化：通过动态扩缩容减少闲置资源消耗，降低长期运行成本。

3.2 适用范围

• GitHub 组织、企业或仓库管理员。
• 拥有 Kubernetes 集群（v1.19+）的团队或个人。
• 需要替代 GitHub 托管 runner 以满足自定义需求的用户。

4. 使用方法和配置说明

4.1 部署前准备

4.1.1 依赖环境

• Kubernetes 集群（v1.19+，支持 CustomResourceDefinitions 和 HPA）。
• Helm 3.0+（推荐，用于简化部署；或直接使用 kubectl 部署 YAML）。
• GitHub 访问凭证：
  • 个人访问令牌（PAT）：需包含 repo（仓库级）或 admin:org（组织级）权限，用于 runner 注册。
  • （可选）GitHub App 凭证：企业级场景下可使用 App 认证替代 PAT，提升安全性。

4.2 部署步骤

4.2.1 使用 Helm 部署（推荐）

1. 添加 Helm 仓库

   bash
   helm repo add self-hosted-k8s-runner https://machine-learning-apps.github.io/self-hosted-k8s-runner
   helm repo update
   

2. 创建配置文件
   创建 values.yaml 配置 runner 基本信息（示例内容见 4.4 节）：

   yaml
   github:
     owner: "<your-github-org-or-username>"  # 组织/用户名
     repository: "<your-repo-name>"          # 可选，指定仓库（不填则为组织级 runner）
     token: "<your-github-pat>"              # GitHub PAT（通过 Secret 注入更安全，见 4.3 节）
   runner:
     labels: ["k8s-runner", "custom-label"]  # 自定义标签
     resources:
       requests:
         cpu: "1"
         memory: "2Gi"
       limits:
         cpu: "2"
         memory: "4Gi"
   autoscaling:
     enabled: true
     minReplicas: 1
     maxReplicas: 5
   

3. 部署 Helm Chart

   bash
   helm install my-runner self-hosted-k8s-runner/self-hosted-k8s-runner -f values.yaml --namespace github-runner --create-namespace
   

4.2.2 使用 kubectl 部署（手动配置）

1. 创建 Secret 存储敏感信息

   yaml
   # github-secret.yaml
   apiVersion: v1
   kind: Secret
   metadata:
     name: github-runner-secret
     namespace: github-runner
   type: Opaque
   data:
     GITHUB_TOKEN: <base64-encoded-pat>  # 替换为 PAT 的 Base64 编码值
   

   应用配置：

   bash
   kubectl apply -f github-secret.yaml -n github-runner
   

2. 部署 Runner Deployment
   创建 runner-deployment.yaml（核心配置示例）：

   yaml
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: github-runner
     namespace: github-runner
   spec:
     replicas: 2  # 初始 runner 数量
     selector:
       matchLabels:
         app: github-runner
     template:
       metadata:
         labels:
           app: github-runner
       spec:
         containers:
         - name: runner
           image: machinelearningapps/self-hosted-k8s-runner:latest  # 官方镜像
           env:
           - name: GITHUB_OWNER
             value: "<your-github-org>"  # 组织名或用户名
           - name: GITHUB_REPOSITORY
             value: "<your-repo>"        # 可选，指定仓库（不填则为组织级）
           - name: GITHUB_TOKEN
             valueFrom:
               secretKeyRef:
                 name: github-runner-secret
                 key: GITHUB_TOKEN
           - name: RUNNER_LABELS
             value: "k8s,linux,x64"      # 自定义标签
           resources:
             requests:
               cpu: "1"
               memory: "2Gi"
             limits:
               cpu: "2"
               memory: "4Gi"
   

   应用部署：

   bash
   kubectl apply -f runner-deployment.yaml -n github-runner
   

4.3 动态扩缩容配置

通过 Kubernetes HPA（Horizontal Pod Autoscaler）实现基于工作流队列的自动扩缩容：

yaml
# hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: github-runner-hpa
  namespace: github-runner
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: github-runner
  minReplicas: 1
  maxReplicas: 10
  metrics:
  - type: External
    external:
      metric:
        name: github_actions_queue_length
        selector:
          matchLabels:
            owner: "<your-github-org>"
            repository: "<your-repo>"  # 可选
      target:
        type: Value
        value: 2  # 每个 runner 处理的队列长度阈值

应用 HPA 配置：

bash
kubectl apply -f hpa.yaml -n github-runner

5. 配置参数详解

5.1 核心环境变量

5.2 Helm 配置参数（values.yaml）

通过 Helm 部署时，可通过 values.yaml 自定义以下关键参数：

yaml
# 基础配置
github:
  owner: "my-org"               # 组织/用户名
  repository: "my-repo"         # 可选，仓库名
  token: ""                     # 建议通过 --set-file 或 Secret 注入

# Runner 配置
runner:
  name: "runner-{{ .Release.Name }}-{{ .Pod.Name }}"  # 名称模板
  labels: "k8s,helm"            # 标签
  ephemeral: false              # 一次性 runner
  workDir: "/home/runner/_work" # 工作目录

# 资源配置
resources:
  requests:
    cpu: "1"
    memory: "2Gi"
  limits:
    cpu: "2"
    memory: "4Gi"

# 扩缩容配置
autoscaling:
  enabled: true                 # 启用 HPA
  minReplicas: 1
  maxReplicas: 10
  targetQueueLength: 2          # 队列长度阈值

6. 部署示例

6.1 Helm 快速部署（组织级 runner）

bash
helm install github-runner self-hosted-k8s-runner/self-hosted-k8s-runner \
  --namespace github-runner --create-namespace \
  --set github.owner=my-org \
  --set github.token=$(cat ./github-pat.txt) \  # 从文件读取 PAT
  --set runner.labels=k8s,org-runner \
  --set autoscaling.enabled=true

6.2 Kubernetes 单仓库 runner 部署 YAML

yaml
# 完整部署示例（仓库级 runner）
apiVersion: v1
kind: Namespace
metadata:
  name: github-runner
---
apiVersion: v1
kind: Secret
metadata:
  name: github-runner-secret
  namespace: github-runner
type: Opaque
data:
  GITHUB_TOKEN: <base64-encoded-pat>  # 替换为实际 PAT 的 Base64 编码
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: github-runner
  namespace: github-runner
spec:
  replicas: 2
  selector:
    matchLabels:
      app: github-runner
  template:
    metadata:
      labels:
        app: github-runner
    spec:
      containers:
      - name: runner
        image: machinelearningapps/self-hosted-k8s-runner:latest
        env:
        - name: GITHUB_OWNER
          value: "my-user"
        - name: GITHUB_REPOSITORY
          value: "my-repo"
        - name: GITHUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: github-runner-secret
              key: GITHUB_TOKEN
        - name: RUNNER_LABELS
          value: "repo-runner,linux"
        - name: RUNNER_EPHEMERAL
          value: "true"
        resources:
          requests:
            cpu: "500m"
            memory: "1Gi"
          limits:
            cpu: "1"
            memory: "2Gi"

7. 常见问题

7.1 Runner 注册失败

• 排查方向：检查 GITHUB_TOKEN 权限（需 repo 或 admin:org）、网络连通性（能否访问 api.github.com）。
• 解决方法：重新生成 PAT 并确保权限正确，配置代理（若需）。

7.2 扩缩容不触发

• 排查方向：检查 HPA 配置是否正确、外部指标（如队列长度）是否正常采集。
• 解决方法：确认 github_actions_queue_length 指标是否可用，调整 HPA 目标阈值。

7.3 任务执行失败

• 排查方向：查看 runner 容器日志（kubectl logs <pod-name>），检查工作流步骤与 runner 环境是否兼容。
• 解决方法：通过 RUNNER_LABELS 匹配工作流标签，或自定义 runner 镜像预装依赖。

8. 参考链接

• https://github.com/machine-learning-apps/self-hosted-k8s-runner
• https://docs.github.com/en/actions/hosting-your-own-runners
• Kubernetes HPA 文档