使用自托管 Runner

适用场景

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

配置说明

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

主机Runner的配置安装

步骤一：进入 Runner 管理页面

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

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

步骤二：创建主机 Runner

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

步骤三：填写 Runner 配置

字段	是否必填	说明
Runner 名称	必填	自定义 Runner 的标识名称，如 `CI-runner`，用于在管理页面区分不同 Runner
安装准备	—	环境前置条件及自动安装选项（见下方说明）
Runner 工作目录	必填	Runner 在主机上的工作目录路径，系统会自动生成默认值（如 `/opt/runner_1783325952`），可按需修改
Runner 环境镜像	必选	选择 Runner 运行的操作系统镜像，支持 Ubuntu 和 EulerOS
CPU 架构	必选	选择主机的 CPU 架构，支持 x64 和 arm64
自定义标签	选填	为 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`
标签颜色	选填	为标签选择颜色，便于在管理页面直观区分
操作	—	点击"删除"移除该标签

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

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

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

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

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

# 使用自托管 Runner
if [ -f 'which curl' ]; then
  curl -# -k -o ${RUNNER_INSTALL_FILE} ${RUNNER_INSTALL_URL}
else
  wget ... ${RUNNER_INSTALL_URL}
fi

登录到目标主机，将复制的脚本粘贴到终端执行：

# 粘贴并执行从页面复制的完整脚本
# 脚本会自动完成：下载 Runner → 安装依赖 → 注册到平台 → 启动服务

重要：

目标主机必须有访问外网的权限。

脚本需要 sudo 权限执行，请确保当前用户拥有 sudo 权限。

安装脚本中包含一次性注册 Token，请勿泄露或重复使用。

步骤五：验证 Runner 状态

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

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

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

# .gitcode/workflows/gpu-build.yml
stages:
  - name: gpu-test
    jobs:
      - name: cuda-compile
        runs-on: [self-hosted, euler, x64, gpu]
        steps:
          - run: nvcc -o myapp myapp.cu

# 使用自定义标签精确匹配
jobs:
  - name: backend-deploy
    runs-on: [self-hosted, env-prod, server-backend]
    steps:
      - run: ./deploy.sh

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

Kubernetes Runner 的配置安装

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

步骤一：进入 Runner 管理页面

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

步骤二：创建 Kubernetes Runner

点击页面右上角的 "+ 新增自定义 Runner" 按钮。
在弹出的下拉菜单中选择 "新增 Kubernetes Runner"，进入 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 架构	非必填	选择 Pod 运行的 CPU 架构，支持 x64（默认）和 arm
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 相同，标签表格包含标签名称、默认值、标签颜色和操作四列。系统会根据所选 CPU 架构自动生成默认标签行（如 arch=x64），你可以点击 "+ 新增自定义标签" 添加更多标签（如 env=staging、team=backend 等）。

步骤四：创建 Runner

完成表单配置后，点击左下角的 "创建" 按钮。
系统将在指定的 Kubernetes 集群和命名空间中自动部署 Runner Pod。
如需放弃本次配置，点击 "取消" 返回上一页。

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

返回 AtomGit 平台的 项目设置 → Runners 页面，切换到 Kubernetes-Runner 标签页。
在 Runner 列表中确认新创建的 Runner 状态为在线（绿色标识）。
如 Runner 显示为离线，请检查：
- 集群 URL 和 Kubernetes config 凭证是否正确
- 目标命名空间是否存在
- 集群网络是否可访问 AtomGit 平台

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

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

步骤六：在 workflow 中使用 Kubernetes Runner

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

# .gitcode/workflows/k8s-build.yml
jobs:
  - name: container-build
    runs-on: [self-hosted, k8s, arch-x64]
    steps:
      - uses: checkout
      - run: docker build -t myapp:latest .

# 使用自定义标签精确匹配
jobs:
  - name: staging-test
    runs-on: [self-hosted, env-staging, team-backend]
    steps:
      - run: npm test

主机 Runner 与 Kubernetes Runner 对比

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

自托管 Runner 标签规则

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

自动生成标签：创建 Runner 时，系统根据所选的环境镜像和 CPU 架构自动生成标签（如 os=euler、arch=x64），并默认加入 self-hosted 标签用于区分托管/自托管类型。
自定义标签：通过创建 Runner 时的"自定义标签"表格添加，支持设置标签名称、默认值和标签颜色，用于精确匹配和可视化管理。
标签组：可在管理页面为 Runner 设置 group 属性，用于组织归类。

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

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

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

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

组织级 vs 项目级 Runner

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

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

Runner 更新

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

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

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

适用场景​

配置说明​

主机Runner的配置安装​

Kubernetes Runner 的配置安装​

主机 Runner 与 Kubernetes Runner 对比​

自托管 Runner 标签规则​

组织级 vs 项目级 Runner​

Runner 更新​