在当今快速迭代的软件开发领域如何将代码高效、可靠地转化为可运行的软件并交付给用户是每个开发团队面临的共同挑战。传统的交付流程往往涉及多个割裂的工具和手动步骤从代码提交、构建、测试到部署不仅效率低下还容易出错。如果你正在为构建复杂的 CI/CD 流水线而头疼或者希望将交付流程更好地集成到团队日常使用的平台中那么 GitHub 推出的Agent Apps功能或许正是你寻找的解决方案。本文将深入解析 GitHub Agent Apps 如何将软件交付工作流无缝引入平台内部从核心概念、环境搭建到实战配置为你提供一套从入门到落地的完整指南帮助你构建更自动化、更内聚的交付体验。1. 背景与核心概念什么是 GitHub Agent Apps在深入技术细节之前我们首先要理解几个关键概念GitHub Actions、自托管运行器Self-hosted runners以及 Agent Apps 所要解决的核心问题。GitHub Actions是 GitHub 提供的自动化平台允许你创建由代码仓库事件如 push、pull request触发的工作流Workflow。这些工作流由一系列作业Job和步骤Step组成可以在 GitHub 托管的虚拟机或你自己提供的机器上运行。自托管运行器是你自己配置并管理的服务器用于运行 GitHub Actions 的作业。与 GitHub 托管的运行器相比自托管运行器让你可以完全控制操作系统、软件环境、网络和安全策略这对于需要访问内部资源、使用特定硬件或遵守严格安全合规要求的场景至关重要。然而传统的自托管运行器管理模式存在一些痛点管理分散运行器需要手动在每台服务器上安装和注册大规模部署时运维成本高。权限宽泛运行器通常以较高权限运行存在一定的安全风险。与平台集成度低运行器作为“外部”资源其状态、日志和生命周期管理与 GitHub 平台的集成不够紧密。GitHub Agent Apps正是为了应对这些挑战而生。它本质上是一种新型的自托管运行器管理方式。通过 Agent Apps你可以将运行器集群作为一个“应用程序”来管理和扩展。这些运行器称为“Agents”通过一个轻量级的控制器Agent Controller与 GitHub 通信由 GitHub 统一调度和管理任务。这带来了几个根本性的改变平台内聚软件交付的完整工作流从代码到部署更加紧密地集成在 GitHub 平台内部进行编排和监控。集中管理可以通过 GitHub 的界面或 API 集中查看、管理所有 Agent 的状态和任务。增强安全支持更细粒度的权限控制和网络策略任务在隔离的环境中运行。弹性伸缩更容易与云平台或内部编排系统如 Kubernetes集成实现运行器资源的自动伸缩。简单来说Agent Apps 将软件交付工作流的“执行引擎”更优雅、更安全、更可控地引入了 GitHub 平台生态中使得 CI/CD 不再是平台外挂的流程而是平台原生能力的一部分。2. 环境准备与架构说明在开始实战之前我们需要明确 Agent Apps 的架构和所需环境。与安装单个自托管运行器不同Agent Apps 涉及两个核心组件Agent Controller这是一个运行在你基础设施上的服务负责与 GitHub 通信接收工作流任务并将其分发给可用的 Agents。一个 Controller 可以管理多个 Agent。Agents实际执行工作流任务的计算单元。它们由 Controller 创建和管理。Agent 可以运行在虚拟机、物理机或容器中。环境要求GitHub 账户与仓库你需要一个 GitHub 账户并且对目标仓库或组织拥有管理员权限以便安装和配置 GitHub App。服务器/虚拟机用于运行 Agent Controller。推荐使用 Linux 系统如 Ubuntu 20.04/22.04 LTS。计算资源用于运行 Agents。这可以是与 Controller 同一环境的虚拟机、独立的服务器集群或者一个 Kubernetes 集群。Agent 本身资源需求取决于你要运行的任务如编译、测试。网络连通性运行 Controller 的服务器需要能够访问api.github.com以及 GitHub Actions 服务所需的其他端点。同时你的 Agents 需要能访问构建所需的内部资源如私有包仓库、内部数据库等。版本说明Agent Apps 是 GitHub 不断演进的功能。本文的示例基于当前撰写时通用的公开模式和 API。具体的安装命令和配置细节请务必以 GitHub 官方文档 为准因为界面和命令可能更新。3. 核心配置与原理拆解要使用 Agent Apps核心是通过一个 GitHub App 来建立 GitHub 与你自托管基础设施之间的信任和通信桥梁。这与直接使用个人访问令牌PAT注册传统运行器有本质区别。3.1 创建 GitHub App这是整个流程的起点。GitHub App 充当了认证和授权的中心。进入 GitHub 账户Settings-Developer settings-GitHub Apps-New GitHub App。填写基本信息如 App 名称、主页 URL可填仓库地址。Webhook通常不需要除非你有高级需求可以暂时禁用。权限Permissions这是关键。需要为 App 配置以下权限Administration:Read(用于管理运行器)Checks:Read(用于获取检查任务)Metadata:Read(必选)如果你希望 Agent 能访问仓库内容还需要Contents:Read。订阅事件Subscribe to events至少需要订阅Workflow job事件。创建后你会获得一个App ID。接下来需要生成一个Private key.pem 文件并妥善保存。最后将创建的 GitHub App安装Install到你的目标组织或仓库。3.2 理解认证流程JWT 与安装访问令牌Agent Controller 如何证明自己是合法的它使用 GitHub App 的私钥生成一个JSON Web Token (JWT)并用这个 JWT 向 GitHub API 申请一个短期的安装访问令牌Installation Access Token。这个安装令牌才拥有我们之前为 App 配置的权限用于后续创建、注册和管理运行器Agents。这种机制比长期有效的 PAT 更安全。3.3 Agent 与工作流的匹配当仓库中触发了一个工作流并且该工作流作业的runs-on标签与你通过 Agent Apps 配置的标签匹配时GitHub Actions 服务会将任务排队。Agent Controller 监听到有新任务会选择一个空闲的 Agent 来领取并执行该任务。这个过程对工作流文件本身几乎是透明的你只需要使用正确的标签。4. 完整实战案例使用 Actions Runner Controller (ARC) 部署 Agent Apps目前社区最流行且被 GitHub 推荐的实现方式是使用Actions Runner Controller (ARC)这是一个开源项目它极大地简化了在 Kubernetes 集群中部署和管理 GitHub Actions 运行器的过程。我们将以此为例进行实战。假设场景我们有一个组织my-org希望在内部的 Kubernetes 集群中运行为其仓库my-repo定义的 CI/CD 工作流。4.1 前期准备Kubernetes 集群与 Helm准备一个可用的 Kubernetes 集群如 Minikube, Kind, 或云厂商的 K8s 服务。安装kubectl命令行工具并配置好集群连接。安装helm包管理工具。4.2 创建 GitHub App 并获取凭证按照3.1节的步骤为你的组织my-org创建并安装 GitHub App。记录下APP_ID(如123456)下载的私钥文件my-app-private-key.pem安装后的INSTALLATION_ID(可以在安装设置的 URL 中找到)4.3 使用 Helm 部署 Actions Runner ControllerARC 提供了 Helm Chart方便我们部署。# 添加 ARC 的 helm 仓库 helm repo add actions-runner-controller https://actions-runner-controller.github.io/actions-runner-controller helm repo update # 创建一个命名空间 kubectl create ns actions-runner-system # 使用 helm 安装 ARC 的核心组件 # 需要提前将 GitHub App 的私钥内容存入一个 Kubernetes Secret kubectl create secret generic controller-manager-secret \ -n actions-runner-system \ --from-filegithub_app_private_key./my-app-private-key.pem # 安装 chart helm upgrade --install arc actions-runner-controller/actions-runner-controller \ -n actions-runner-system \ --set github_app_id$APP_ID \ --set github_app_installation_id$INSTALLATION_ID \ --set syncPeriod1m安装成功后检查 Pod 状态kubectl get pods -n actions-runner-system你应该看到arc-actions-runner-controller-xxx和arc-gha-runner-scale-set-xxx等 Pod 在运行。4.4 部署 RunnerDeployment 创建 Agent 池现在我们需要定义一组运行器Agent。ARC 使用RunnerDeployment和AutoscalingRunnerSet等 CRD自定义资源来管理。创建一个 YAML 文件runner-deployment.yaml# runner-deployment.yaml apiVersion: actions.summerwind.dev/v1alpha1 kind: RunnerDeployment metadata: name: my-org-runner-deployment namespace: actions-runner-system # 建议与 controller 同命名空间 spec: template: spec: # 这个运行器属于哪个 GitHub 范围组织级别。 organization: my-org # 运行器将显示的标签工作流中 runs-on 可引用 labels: - k8s-agent - medium # 运行器容器使用的 Docker 镜像 image: summerwind/actions-runner:latest # 运行器容器资源请求与限制 resources: requests: cpu: 500m memory: 1Gi limits: cpu: 1 memory: 2Gi # 可以在这里挂载存储卷等应用这个配置kubectl apply -f runner-deployment.yaml稍等片刻ARC 控制器会创建对应的 Pod 来充当运行器 Agent。你可以查看运行器状态kubectl get runners -n actions-runner-system同时在 GitHub 组织my-org的Settings - Actions - Runners页面你应该能看到一个名为my-org-runner-deployment-xxxx的新运行器在线并带有k8s-agent和medium标签。4.5 创建工作流文件使用 Agent现在你可以在my-org下的任何仓库中创建使用这些 Agent 的工作流。在仓库.github/workflows/目录下创建ci.yml# .github/workflows/ci.yml name: CI on K8s Runner on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build-and-test: # 关键使用我们自定义的标签来匹配 Agent runs-on: [self-hosted, k8s-agent, medium] steps: - name: Checkout code uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 18 - name: Install dependencies run: npm ci - name: Run tests run: npm test - name: Build project run: npm run build4.6 运行与验证将上述工作流文件推送到main分支或创建一个 Pull Request。触发工作流后在仓库的Actions标签页你可以看到新的工作流运行。点击进入详情可以看到作业正在“等待运行器”。几秒内ARC 调度器会将任务分配给一个空闲的 Agent Pod。作业开始执行日志会实时输出。你可以同时在 Kubernetes 中观察对应 Pod 的日志kubectl logs -f runner-pod-name -n actions-runner-system作业完成后Agent Pod 可能会被回收取决于配置实现资源动态利用。5. 常见问题与排查思路在部署和使用 Agent Apps 过程中你可能会遇到以下问题问题现象常见原因解决思路Controller Pod 启动失败1. GitHub App 凭证错误ID、安装ID、私钥。2. 网络无法访问api.github.com。1. 检查kubectl describe pod查看错误事件确认 Secret 已正确挂载且内容无误。2. 在集群内 Pod 中尝试curl https://api.github.com测试连通性。Runner Pod 创建成功但 GitHub 上显示“离线”1. Controller 无法为 Runner 生成有效的注册令牌。2. Runner Pod 网络策略阻止其回连 GitHub。1. 检查 Controller 日志中是否有令牌申请错误。2. 检查 Runner Pod 日志看是否在尝试注册时遇到网络或认证错误。确保 Pod 有出口网络权限。工作流任务一直“等待运行器”1. 工作流中runs-on标签与 RunnerDeployment 中定义的labels不匹配。2. 所有匹配的 Runner 都处于“忙碌”状态。1. 仔细核对标签大小写敏感。确保self-hosted标签存在。2. 查看 GitHub Runner 列表确认有闲置 Runner。考虑增加replicas数量或配置自动伸缩。Runner Pod 执行任务失败1. Pod 资源CPU/内存不足。2. 缺少必要的工具或依赖如 docker、git。1. 调整RunnerDeployment中的resources限制。2. 使用自定义的 Docker 镜像基于summerwind/actions-runner预装所需工具或在工作流步骤中安装。私有仓库拉取失败Runner 没有访问仓库内容的权限。确保为 GitHub App 配置了Contents: Read权限。对于需要推送的流程可能还需要Write权限。通用排查命令# 查看 Controller 日志 kubectl logs deployment/arc-actions-runner-controller -n actions-runner-system -f # 查看特定 Runner Pod 日志 kubectl logs runner-pod-name -n actions-runner-system # 查看 Runner 自定义资源状态 kubectl describe runner runner-name -n actions-runner-system # 查看 RunnerDeployment 状态 kubectl describe runnerdeployment my-org-runner-deployment -n actions-runner-system6. 最佳实践与工程建议将 Agent Apps 引入生产环境需要考虑安全性、可靠性和成本效益。安全隔离命名空间隔离将 ARC 组件和 Runner Pod 部署在独立的命名空间中并配置合理的 NetworkPolicies限制不必要的网络访问。最小权限原则为 GitHub App 配置尽可能小的权限范围。如果只为特定仓库服务就安装到仓库而非整个组织。镜像安全使用自己构建的 Runner 基础镜像定期更新以修补安全漏洞避免使用:latest标签。Secret 管理使用 Kubernetes Secrets 或外部 Secret 管理工具如 HashiCorp Vault安全地存储 GitHub App 私钥并定期轮换。资源管理与自动伸缩资源限制务必为 Runner Pod 设置resources.requests和resources.limits防止单个任务耗尽节点资源。利用 HorizontalRunnerAutoscalerARC 提供了HorizontalRunnerAutoscalerCRD可以根据 GitHub Actions 队列中的待处理作业数量自动调整 Runner 的数量。这是实现成本优化的关键。# 示例基于工作流队列长度的自动伸缩 apiVersion: actions.summerwind.dev/v1alpha1 kind: HorizontalRunnerAutoscaler metadata: name: my-org-runner-autoscaler spec: scaleTargetRef: name: my-org-runner-deployment minReplicas: 1 maxReplicas: 10 metrics: - type: TotalNumberOfQueuedAndInProgressWorkflowRuns repositoryNames: - my-org/my-repo使用 Spot 实例/廉价节点在云平台上可以让 Runner Pod 运行在 Spot 实例或预付费节点上以大幅降低计算成本。配置与维护标签策略设计清晰的标签体系。例如按功能 (build,test)、按资源大小 (small,medium,large)、按环境 (prod,staging) 来标签化 Runner。工作流根据需求选择。持久化存储如果工作流需要在多个步骤间缓存文件如node_modules,~/.cache可以为 Runner 配置持久化存储卷如 PVC或使用actions/cache等 Action。监控与告警监控 Runner 集群的健康状态包括 Pod 重启次数、资源使用率、任务排队时间等。设置告警以便在 Runner 资源不足或控制器异常时及时通知。网络与访问出口代理如果公司网络需要通过代理访问外网需要为 Runner Pod 配置HTTP_PROXY/HTTPS_PROXY环境变量。访问内部服务Runner Pod 可能需要访问内部数据库、Artifactory 等。确保 Kubernetes 网络策略或服务网格如 Istio允许这种访问。通过 GitHub Agent Apps 和 ARC 的实践我们成功地将软件交付工作流的执行环境深度集成到了 Kubernetes 和 GitHub 平台之中。这种模式不仅提供了强大的自动化能力和资源弹性还通过集中管理和增强的安全模型降低了运维复杂度。从手动管理服务器上的运行器脚本到声明式地定义和管理一个可伸缩的 Runner 集群这是 DevOps 实践的一次重要演进。建议从一个小型非关键项目开始试点逐步熟悉配置、监控和故障排查流程待模式成熟后再推广到核心业务流水线中。
