跳到主要内容

使用自托管 Runner

本文档介绍如何部署和使用主机 Runner 和 Kubernetes Runners集，包括配置安装、标签规则以及组织级与项目级 Runner 的管理。

当官方托管 Runner 无法满足需求——需要特殊硬件（GPU、特定架构）、内网环境、自定义工具链——可部署自托管 Runner。

配置说明​

AtomGit Action支持主机和Kubernetes两类自定义Runner，配置方式如下。

主机Runner的配置安装​

步骤一：进入 Runner 管理页面

  1. 进入目标项目/组织页面，点击顶部导航栏的 项目设置/组织设置。
  2. 在左侧边栏中，展开 Actions 分组，点击 Runners。
  3. 进入"Runners"页面，页面顶部有两个标签页：主机 Runner 和 Kubernetes Runners集s集，默认选中"主机 Runner"。

说明：首次进入时页面显示"暂无数据"，表示该仓库/组织尚未配置任何 Runner。

步骤二：创建主机 Runner

  1. 点击页面右上角的 "+ 新增自定义 Runner" 按钮。
  2. 在弹出的下拉菜单中选择 "新增主机 Runner"，进入 Runner 配置表单。

步骤三：填写 Runner 配置

字段是否必填说明
Runner 名称必填自定义 Runner 的标识名称，如 CI-runner，用于在管理页面区分不同 Runner
安装准备—环境前置条件及自动安装选项（见下方说明）
Runner 工作目录必填Runner 在主机上的工作目录路径，系统会自动生成默认值（如 /opt/runner_1783325952），可按需修改
Runner 环境镜像必选选择 Runner 运行的操作系统镜像，支持 Ubuntu 和 EulerOS
自定义标签选填为 Runner 添加自定义标签，用于在 workflow 中精确匹配（见下方说明）

安装准备选项：

页面提示："您的主机需要有访问外网权限，并且有安装 Java 8、Git 和 Docker 环境。"

系统提供以下 4 个复选框，默认全部勾选：

选项默认说明
☑ 自动安装 JDK勾选安装脚本自动检测并安装 JDK 环境
☑ 自动安装 Git勾选安装脚本自动检测并安装 Git
☑ 自动安装 Docker勾选安装脚本自动检测并安装 Docker
☑ 重启免注册勾选主机重启后 Runner 自动恢复注册状态，无需重新执行注册脚本

提示：如果主机上已预装了部分环境，可以取消对应选项，安装脚本将跳过已安装的组件。建议保持"重启免注册"勾选，以确保 Runner 服务持久可用。

自定义标签配置：

自定义标签用于在 workflow 的 runs-on 中精确匹配目标 Runner。标签表格包含以下列：

列名是否必填说明
标签名称必填标签的 key，如 os、arch、env、server
默认值选填标签的默认 value，如 euler、x64、prod、backend
标签颜色选填为标签选择颜色，便于在管理页面直观区分
操作—点击"删除"移除该标签

系统会根据所选的环境镜像自动生成默认标签行（如 os=euler），你可以在此基础上点击 "+ 新增自定义标签" 添加更多标签。

步骤四：获取并执行安装脚本

  1. 完成表单配置后，点击左下角的 "获取执行脚本" 按钮。
  2. 系统会根据你的配置自动生成一段 Shell 安装脚本，显示在表单下方的"执行脚本"区域。
  3. 点击脚本区域右上角的 复制图标，一键复制完整脚本。

生成的脚本示例结构如下：

export RUNNER_INSTALL_URL=...
export RUNNER_INSTALL_FILE=install-octopus-runner.sh

# 优先使用 curl，不可用时回退到 wget
if [ -f 'which curl' ]; then
  curl -# -k -o ${RUNNER_INSTALL_FILE} ${RUNNER_INSTALL_URL}
else
  wget ... ${RUNNER_INSTALL_URL}
fi
  1. 登录到目标主机，将复制的脚本粘贴到终端执行：
# 粘贴并执行从页面复制的完整脚本
# 脚本会自动完成：下载 Runner → 安装依赖 → 注册到平台 → 启动服务

重要：

  • 目标主机必须有访问外网的权限。
  • 脚本需要 sudo 权限执行，请确保当前用户拥有 sudo 权限。
  • 安装脚本中包含一次性注册 Token，请勿泄露或重复使用。

步骤五：验证 Runner 状态

  1. 脚本执行成功后，返回 AtomGit 平台的 项目设置 → Runners 页面。
  2. 在 Runner 列表中确认新创建的 Runner 状态为 在线（绿色标识）。
  3. 如 Runner 显示为离线，请检查主机网络连通性和脚本执行日志。

步骤六：在 workflow 中使用自托管 Runner

通过 runs-on 指定 Runner 标签来匹配自托管 Runner：

# .gitcode/workflows/gpu-build.yml
stages:
  gpu-test:
    name: GPU 测试
    jobs:
      name: cuda-compile
      runs-on: [self-hosted, euler, x64, gpu]
      steps:
        - run: nvcc -o myapp myapp.cu
# 使用自定义标签精确匹配
jobs:
  backend-deploy:
    name: backend-deploy
    runs-on: [self-hosted, env=prod, server=backend]
    steps:
      - run: ./deploy.sh

标签匹配规则：runs-on 中列出的所有标签必须同时存在于 Runner 的标签集合中，才视为匹配成功。Runner 注册时的标签（含自动生成和自定义标签）构成其完整标签集。

Kubernetes Runners集 的配置安装​

Kubernetes Runners集 以 Pod 形式运行在你的 Kubernetes 集群中，支持弹性伸缩和资源隔离，适合需要容器化执行环境、按需扩缩容的场景。

步骤一：进入 Runner 管理页面

  1. 进入目标项目/组织页面，点击顶部导航栏的 项目设置/组织设置。
  2. 在左侧边栏中，展开 Actions 分组，点击 Runners。
  3. 进入"Runners"页面，点击顶部的 Kubernetes Runners集s集 标签页。

步骤二：创建 Kubernetes Runners集

  1. 点击页面右上角的 "+ 新增自定义 Runner" 按钮。
  2. 在弹出的下拉菜单中选择 "新增 Kubernetes Runners集"，进入 Runner 配置表单。

步骤三：填写 Runner 配置

字段是否必填说明
名称必填自定义 Runner 的标识名称，如 k8s-runner-prod
集群 URL必填Kubernetes API Server 的访问地址，如 https://10.0.0.1:6443
Kubernetes config 凭证必填集群的 kubeconfig 凭证内容，用于 Runner 连接和认证集群
命名空间必填Runner Pod 部署的目标命名空间，默认为 default，可按需修改
镜像名称非必填Runner 运行的容器镜像，默认为 Ubuntu，由系统预设
CPU必填每个 Runner Pod 请求的 CPU 核数，默认 1 核
内存必填每个 Runner Pod 请求的内存大小，默认 4 GB
最小 Runner 数量必填弹性伸缩的下限，集群中始终保持的最少 Pod 数，默认 1
最大 Runner 数量必填弹性伸缩的上限，集群中最多可扩展到的 Pod 数，默认 1
自定义标签选填为 Runner 添加自定义标签，用于在 workflow 中精确匹配

集群连接配置说明：

  • 集群 URL：即 Kubernetes API Server 的地址，可在集群的 kubeconfig 文件中找到 server 字段对应的值。
  • Kubernetes config 凭证：即 kubeconfig 文件的内容，包含集群的证书和认证信息。获取方式：
    1. 在集群管理节点执行 cat ~/.kube/config 获取完整内容。
    2. 或在云平台控制台的集群详情页下载 kubeconfig 文件，将其内容完整粘贴到输入框中。

安全提示：Kubernetes config 凭证包含集群的访问证书和密钥，请妥善保管，避免泄露。

弹性伸缩配置说明：

配置项说明
最小 Runner 数量集群中始终保持的 Runner Pod 数量，即使没有流水线任务也会保留，确保任务到来时可立即调度
最大 Runner 数量当流水线任务并发量增大时，Runner Pod 可扩展到的最大数量
  • 当 最小 = 最大 = 1 时，表示固定 1 个 Runner Pod，不进行弹性伸缩。
  • 如需支持并发执行，可将最大数量调大。例如：最小 1、最大 5，表示空闲时保留 1 个 Pod，高峰时可扩展到 5 个。

自定义标签配置：

与主机 Runner 相同，标签表格包含标签名称、默认值、标签颜色和操作四列，你可以点击 "+ 新增自定义标签" 添加更多标签（如 env=staging、team=backend 等）。

步骤四：创建 Runner

  1. 完成表单配置后，点击左下角的 "创建" 按钮。
  2. 系统将在指定的 Kubernetes 集群和命名空间中自动部署 Runner Pod。

步骤五：验证 Runner 状态并查看详情

  1. 返回 AtomGit 平台的 项目设置 → Runners 页面，切换到 Kubernetes Runners集s集 标签页。
  2. 在 Runner 列表中确认新创建的 Runner 状态为 在线（绿色标识）。
  3. 也可在 Kubernetes 集群中验证 Pod 是否正常运行：
kubectl get pods -n <namespace> | grep runner
  1. 如 Runner 显示为离线，请检查：
    • 集群 URL 和 Kubernetes config 凭证是否正确
    • 目标命名空间是否存在
    • 集群网络是否可访问 AtomGit 平台

**查看 Runner 详情：**在列表中点击 Runner 名称进入详情页，通过 4 个标签页查看更多信息：

  • 基本信息：运行状态、Runner 类型、环境镜像与规格、所属 Runner 组、执行任务数、弹性伸缩配置、最后活跃时间。
  • 标签：展示所有标签的 key-value 对和颜色，点击齿轮图标可编辑标签。
  • Runners 列表：展示当前 Runner 集下所有实时 Pod 实例的名称、状态（空闲/运行中/离线）、IP 和最后活跃时间。
  • 执行历史：展示已执行 Job 的名称、所属流水线、状态、执行时间和执行时长，点击任务名称可跳转到流水线运行详情。

步骤六：在 workflow 中使用 Kubernetes Runners集

通过 runs-on 指定 Runner 标签来匹配 Kubernetes Runners集：

# .gitcode/workflows/k8s-build.yml
jobs:
  container-build:
    name: container-build
    runs-on: [self-hosted, k8s, arch=x64]
    steps:
      - uses: checkout
      - run: npu test
# 使用自定义标签精确匹配
jobs:
  staging-test:
    name: staging-test
    runs-on: [self-hosted, env=staging, team=backend]
    steps:
      - run: npm test

主机 Runner 与 Kubernetes Runners集 对比​

对比维度主机 RunnerKubernetes Runners集
运行形态安装在物理机/虚拟机上，以系统服务运行以 Pod 形式运行在 K8s 集群中
创建方式在页面填写配置后获取安装脚本，手动在主机执行在页面填写集群信息和资源配置后，系统自动部署
资源管理依赖主机自身的硬件资源通过 CPU/内存字段声明资源请求，受 K8s 调度管理
弹性伸缩不支持，每台主机固定运行一个 Runner支持配置最小/最大 Runner 数量，按需扩缩容
环境隔离同一主机上的多个 Job 共享环境每个 Runner Pod 拥有独立的容器环境，天然隔离
适用场景需要 GPU/NPU 等特殊硬件、内网环境、长期运行需要弹性伸缩、容器化执行、环境隔离、快速扩容
前置要求主机有外网访问权限，预装 Java 8、Git、Docker拥有可用的 K8s 集群，提供 kubeconfig 凭证

自托管 Runner 标签规则​

自托管 Runner 的标签体系与官方托管 Runner 不同：

  • 自动生成标签：创建 Runner 时，系统根据所选的环境镜像自动生成标签（如 os=euler），并默认加入 self-hosted 标签用于区分托管/自托管类型。
  • 自定义标签：通过创建 Runner 时的"自定义标签"表格添加，支持设置标签名称（必填）、默认值（选填）和标签颜色，用于精确匹配和可视化管理。另外，Runner支持String和key-value两种标签格式（取决于标签默认值是否填写）。

标签匹配逻辑：workflow 的 runs-on 列表中所有标签必须与 Runner 的标签集合完全匹配，或为Runner标签子集。

# Runner 标签: self-hosted, os=euler, arch=x64, env=prod, server=backend
# workflow处理生产环境业务，需要在生产环境的Runner中运行

# 以下 workflow 可匹配
jobs:
  deploy-prod:
    name: deploy-prod
    runs-on: [self-hosted, env=prod, server=backend]

# 以下 workflow 不可匹配（缺少 env=prod 标签）
jobs:
  deploy-prod:
    name: deploy-prod
    runs-on: [self-hosted, server=backend]

组织级 vs 项目级 Runner​

级别注册入口可服务范围
组织级组织 Settings → Runners该组织下所有项目的流水线，支持对指定项目可用
项目级项目 Settings → Runners仅该项目流水线

推荐：通用 Runner（如标准构建）注册为组织级，专用 Runner注册为项目级。

提示：基于 Runner 的管理便利性考虑，组织级 Runner 必须归属于一个 Runner Group。

Runner 更新​

更新 Runner 需要在 AtomGit 平台重新获取安装脚本并执行：

  1. 进入 项目设置 → Runners 页面，找到目标 Runner。
  2. 删除旧版 Runner，重新点击 "+ 新增自定义 Runner" → "新增主机 Runner"。
  3. 按原有配置重新填写表单（Runner 名称、环境镜像、标签等），点击 "获取执行脚本"。
  4. 在目标主机上执行新生成的安装脚本。

提示：建议在更新前停止当前 Runner 服务，更新完成后再验证服务状态。