github/virga-actions-runner

K8s自托管Actions运行器镜像文档

镜像概述和主要用途

本镜像用于在Kubernetes集群中部署和运行自托管的GitHub Actions运行器，集成了Argo工具和Kubectl命令行工具。主要用途是为GitHub仓库提供自定义的、运行在Kubernetes环境中的Actions执行环境，支持与Kubernetes集群资源的交互及Argo相关工作流的管理。

核心功能和特性

• 自托管GitHub Actions运行器：提供完整的GitHub Actions运行器功能，可注册到指定GitHub仓库/组织，执行工作流任务
• Kubectl集成：内置Kubectl工具，支持直接在运行器中执行Kubernetes资源管理命令（如创建、更新、删除Pod/Deployment等）
• Argo工具支持：集成Argo相关工具（如Argo CD或Argo Workflows客户端），支持Argo工作流的提交、监控和管理操作
• Kubernetes环境适配：镜像设计符合Kubernetes容器化部署规范，支持通过Deployment、StatefulSet等资源类型进行编排
• 轻量级基础：基于精简基础镜像构建，减少资源占用，适合集群环境部署

使用场景和适用范围

• Kubernetes环境CI/CD：需要在Kubernetes集群内部执行GitHub Actions工作流（如构建容器镜像、部署应用到集群）的场景
• 自定义运行器需求：GitHub托管运行器无法满足网络隔离、资源定制或工具依赖需求时，作为自托管替代方案
• Argo工作流集成：工作流中包含Argo CD应用部署、Argo Workflows任务调度等操作的场景
• 企业自托管环境：企业内部需要完全控制CI/CD基础设施，满足数据隐私或合规要求的场景

使用方法和配置说明

前置条件

• 运行环境：Kubernetes集群（v1.21+推荐）
• 权限要求：集群中创建运行器Pod的权限，以及运行器注册所需的GitHub个人访问令牌（PAT）或组织/仓库访问令牌
• 网络要求：运行器Pod需能访问GitHub API（https://api.github.com%EF%BC%89%E5%8F%8AArgo%E7%9B%B8%E5%85%B3%E6%9C%8D%E5%8A%A1%EF%BC%88%E5%A6%82Argo CD服务器）

环境变量配置

运行器注册及功能启用需通过以下环境变量配置：

Kubernetes部署示例（Deployment）

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: github-actions-runner
  namespace: actions-runner
spec:
  replicas: 1
  selector:
    matchLabels:
      app: actions-runner
  template:
    metadata:
      labels:
        app: actions-runner
    spec:
      containers:
      - name: runner
        image: [镜像名称]  # 替换为实际镜像地址
        env:
        - name: GITHUB_REPOSITORY
          value: "your-org/your-repo"  # 替换为目标仓库/组织
        - name: GITHUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: github-runner-secret
              key: token
        - name: RUNNER_LABELS
          value: "k8s,argo,kubectl"
        resources:
          requests:
            cpu: "1"
            memory: "1Gi"
          limits:
            cpu: "2"
            memory: "2Gi"

运行器注册与启动流程

1. 创建GitHub访问令牌：在GitHub账户设置中生成PAT，权限需包含repo（仓库级别）或admin:org（组织级别）
2. 存储令牌：将令牌存入Kubernetes Secret（示例命令）：

   bash
   kubectl create secret generic github-runner-secret -n actions-runner --from-literal=token=your_github_pat_token
   

3. 部署运行器：应用上述Deployment配置，运行器容器启动后会自动使用环境变量注册到指定GitHub仓库/组织
4. 验证注册：在GitHub仓库/组织的「Settings > Actions > Runners」页面查看已注册的运行器状态

工作流使用示例

在GitHub仓库工作流文件（如.github/workflows/k8s-deploy.yml）中，可指定使用该运行器：

yaml
name: Deploy to Kubernetes
on: [push]
jobs:
  deploy:
    runs-on: [self-hosted, k8s, argo]  # 匹配运行器标签
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Deploy to cluster
        run: |
          kubectl apply -f k8s/deployment.yaml  # 使用内置kubectl
          argo workflow submit workflows/deploy.yaml  # 使用内置Argo工具

参考链接

• 项目源码及详细配置：https://github.com/github-developer/self-hosted-runners-anthos/tree/master
• GitHub Actions自托管运行器文档：https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners