阅读导览
自动打包会读取仓库中的工作流文件,在指定的构建机上安装依赖、执行测试和构建命令,并把生成的文件保存为构建产物。你可以在仓库的「工作流」页面查看排队情况、执行日志和下载结果。目前提供 Windows、安卓、Linux、网页和 Docker 模板,不包含苹果平台。
模板是可修改的起点。程序需要先具备对应平台的代码、依赖和构建方式。例如,普通网页不会因为选择 Windows 模板就自动变成桌面应用,依赖 C 语言库的 Go 项目也需要补充交叉编译工具。选择模板后,请先核对项目目录、版本和输出路径。
开始前准备
先确认仓库中有可构建的代码,并已启用「工作流」功能。自动打包入口使用现有的仓库权限:同时具有代码写入和工作流写入权限的人,可以查看、下载模板并把它带入文件编辑器。归档仓库和拉取镜像仓库不能直接通过这个入口修改文件。
然后确认至少有一台匹配模板标签的构建机在线。标签用于选择执行环境,例如 xhgit-linux 代表 Linux 构建环境,xhgit-windows 代表 Windows 构建环境。没有匹配的构建机时,任务会等待,不会转而使用网站服务器执行。构建环境的安装方法见构建机管理。
构建机必须能访问 XHGit、项目的依赖下载地址以及模板中使用的 Actions 地址。下载速度和可达性会影响首次构建时间;网站能正常访问,并不代表独立构建机也能访问全部依赖源。项目有自己的合法镜像源时,可在工作流中按工具的标准配置方式设置。
添加工作流文件
打开仓库「工作流」,进入「自动打包」。选择符合项目技术栈的模板,可以先预览完整内容,也可以下载 YAML 文件自行修改。点击使用模板后,会进入仓库原有的文件编辑器,默认文件位于 .gitea/workflows/,名称类似 xhgit-go.yaml。
文件编辑器中的内容尚未提交。检查主包路径、构建目录、工具版本、任务标签以及产物路径,再填写提交说明。仓库的保护分支规则仍然生效;根据权限选择直接提交或提交到新分支,再通过合并请求审查。模板不会覆盖已经存在的同名文件,也不会绕过分支保护。
提交后,模板默认在推送时运行,并提供手动运行入口。手动运行要求工作流文件已经进入默认分支;在「工作流」页面选中对应工作流,再选择分支执行。先在测试仓库验证命令和输出,再把相同流程用于正式项目。
Go 多平台应用
Go 模板先运行 go test ./...,测试通过后生成 Windows、Linux 的 amd64 和 arm64 程序。主包默认是仓库根目录,程序名称默认是 app。如果入口位于 cmd/server,将 MAIN_PACKAGE 改为 ./cmd/server,并把 BINARY_NAME 改成希望发布的程序名称。
模板从 go.mod 读取 Go 版本,默认设置 CGO_ENABLED=0,适合纯 Go 项目。需要 CGO、系统动态库或平台原生 SDK 的项目,应准备对应平台工具链,必要时拆分到 Windows 或其他专用构建机。模板不会自动把缺失的原生依赖转换为纯 Go 依赖。
每个平台和架构都有单独的产物,归档名称包含系统和架构。Linux 程序使用 tar.gz 保存执行权限;Windows 程序包含 .exe 后缀。下载后解压,再在相匹配的系统上运行。编译成功只说明生成了目标文件,正式发布前仍应执行目标平台的功能测试。
安卓与 Gradle
安卓模板适用于包含 Gradle Wrapper、标准 app 模块的安卓项目。仓库需要提交 gradlew、Wrapper 配置及所需构建文件。模板安装 Java 和 Android SDK,执行单元测试、调试 APK 构建以及发布 AAB 构建;多模块项目或自定义变体,需要同步修改 Gradle 任务和产物路径。
默认 SDK 包含 Android 36 平台与 36.0.0 构建工具。项目采用其他编译 SDK、Java 或 Gradle 版本时,应先按项目兼容关系调整模板。首次安装 Android SDK 会接受相应 SDK 许可证;使用者应确认项目及构建环境符合许可证要求。
调试 APK 方便安装测试,不能当作正式发布签名。AAB 是应用商店使用的发布包,不能像 APK 一样直接安装。正式发布的密钥、密钥密码和别名应放到仓库的机密配置,按项目的 Gradle 签名流程读取。不要把 keystore、密码或包含它们的配置文件提交到代码仓库,也不要把它们纳入产物目录。
Flutter 跨平台应用
Flutter 模板包含三个独立任务:Linux 与网页、安卓、Windows。项目需要已经包含 linux、web、android 和 windows 目录,并确认所用插件支持对应平台。仅支持安卓的项目应删除不适用的任务;不要用空目录绕过检查。
Linux 任务安装桌面依赖并执行 Flutter 测试,生成 Linux 桌面包和网页包。安卓任务生成调试 APK 和发布 AAB。Windows 任务在 Windows 构建机上生成完整的发布目录压缩包。桌面应用通常需要整个目录中的动态库和资源,不能只拿其中一个可执行文件发布。
模板默认使用 Flutter stable。为了重复构建得到一致结果,正式项目应固定已验证的 Flutter 版本,并维护依赖锁文件。Windows 构建机需要 Visual Studio 的桌面 C++ 组件和 Windows SDK;只有 Linux 构建机时,Windows 原生任务会等待匹配环境。安卓正式签名也需要由项目维护者配置。
Node.js 网页和 Docker
网页模板使用 Node.js 24,通过 npm ci 按 package-lock.json 安装依赖,再执行 npm run build,将 dist 归档。采用 pnpm、Yarn 或其他输出目录的项目,应修改安装命令、构建命令和归档路径。构建结果是可下载文件;模板不会自动修改网站或发布到生产服务器。
Docker 模板使用仓库根目录的 Dockerfile,在专用 Docker 构建机中构建镜像。镜像标签包含本次提交 SHA,导出的 image.tar.gz 可以用 docker load 导入。它不会登录镜像仓库、推送镜像或启动生产容器。需要推送时,由维护者自行添加目的仓库和机密,并保持发布权限最小化。
Docker 构建可以执行任意 Dockerfile 指令,应该与普通构建任务分开管理。不要把生产 Docker socket 暴露给任务。xhgit-docker 必须指向独立构建环境;容器内构建服务仍需管理员维护资源限制和清理策略。
自定义脚本与产物下载
自定义模板分别执行 Linux 的 .xhgit/build.sh 和 Windows 的 .xhgit/build.ps1。脚本负责安装或调用项目所需工具,并把最终文件写入 dist。失败时必须返回非零退出码,让工作流正确显示失败;不要在脚本中忽略测试错误后仍生成一个看似成功的压缩包。
在一次运行的详情页可以按任务查看实时日志。构建完成后,产物会显示在同一运行中,具有相应访问权限的用户可以下载。模板默认保留七天,实际保存期限还受站点的工作流设置约束。上传时找不到文件会使任务失败,方便及时发现输出路径配置错误。
归档只包含可分发的结果。不要把整个工作目录、用户目录、.git、环境文件、签名密钥或临时凭据打包上传。私有仓库的产物也应按敏感度管理,不能因为页面需要登录就把生产密钥作为普通产物保存。
任务等待或失败时
一直排队时,先检查标签是否一致、构建机是否在线以及并发槽位是否用完;不要重复点击运行制造更多等待任务。检出失败时检查构建机到 XHGit 的地址和证书。依赖下载失败时检查网络、工具版本和镜像源,避免在日志中输出访问令牌。
编译失败时从第一个实际错误开始排查,确认相同提交在开发环境能够执行相同命令。构建成功但上传失败时,核对产物路径和上传步骤。重新运行会再次执行仓库代码和下载依赖,并不修复工作流本身;修改后应保留提交记录,便于把结果关联到具体代码版本。