XHGit · 产品文档

构建环境与 Runner

部署独立构建机,配置标签、作用域、密钥与任务队列。

01

阅读导览

Runner 是执行工作流的构建环境。用户提交工作流后,XHGit 按任务标签选择可用环境,执行仓库中的命令,再展示日志和产物。本章说明如何选择环境、处理等待和定位错误;环境安装由站点维护者负责。

02

选择匹配的环境

打开仓库“工作流 → 自动打包”,查看各类环境的在线数量。Linux 与网页使用 xhgit-linux,安卓使用 xhgit-android,Windows 原生应用使用 xhgit-windows,Docker 镜像使用 xhgit-docker。

标签表示任务的运行条件。不要只为让任务开始就把 Windows 标签改成 Linux,项目依赖的编译器、SDK 和系统库仍必须匹配。纯 Go 项目可从 Linux 交叉编译 Windows;依赖本地 C 库或桌面工具链的项目需要调整构建方式。

03

提交工作流前检查

  1. 检查 runs-on 是否与页面上的环境标签一致。
  2. 核对项目目录、入口、依赖锁定文件、构建命令与输出目录。
  3. 确认有权限的项目维护者已配置必要的变量和 Secrets。

在线环境为零时,联系项目维护者确认安排。保存模板不会自动安装编译器,也不会创建新的构建机。模板仅提供项目起点,需要按自己的仓库修改。

04

任务为何一直等待

在运行详情区分“等待执行”和“执行中”。没有匹配环境,或构建环境正在运行其他任务时,新任务可能等待。先核对标签和在线数量,再查看是否有同一项目的任务仍在执行。

不要反复点击运行。每次触发可能都会创建新任务,增加等待队列。保留需要排查的一次运行地址;不再需要的任务,可请有权限的维护者取消。

05

按日志定位错误

从最先失败的步骤开始检查。检出代码失败核对仓库权限;依赖安装失败核对网络和版本;编译失败查看报错文件与行号;上传失败检查输出目录是否存在。

“找不到 Java”“SDK 不存在”等提示说明工具链不满足当前项目需要。将失败步骤、提交编号和脱敏日志交给维护者。日志可能含私有地址和凭据,公开前应先检查。

06

构建密钥与签名

发布签名、镜像仓库密码与部署凭据应通过构建 Secrets 提供。工作流只引用密钥名称,不写明文值。版本号等不敏感内容可使用普通变量。

安卓测试 APK 与正式发布包用途不同。正式发布前,需要配置签名并核对包名、版本号和发布渠道。生成安装文件不等于通过应用商店审核。

07

下载与验证结果

运行成功后,进入该次运行的产物区域下载文件。确认系统、架构和提交编号;桌面程序应保留完整目录,不能只取依赖其他文件的可执行程序。

产物可能有保存期限。需要长期下载时,由维护者验证后整理到版本发布。修改构建方式时,正常提交工作流,并在团队仓库中通过合并请求审查。完整步骤见多平台自动打包,其他错误见故障排查。