Gitea Actions Runner 部署与嵌入式 CI/CD 实战

1. Gitea Actions Runner 是什么如果你在嵌入式开发领域摸爬滚打过肯定遇到过这样的场景每次修改完代码都要手动编译、打包固件再上传到测试设备。这个过程不仅枯燥还容易出错。Gitea Actions Runner 就是来解决这个痛点的。简单来说Runner 就像是你团队里的一个机器人助手。当你把代码推送到 Gitea 仓库时它会自动帮你完成编译、测试、打包等一系列工作。特别适合单片机开发这类需要频繁编译固件的场景。我去年在一个智能家居项目中使用 Runner 后团队效率提升了至少 30%。最明显的变化是凌晨两点再也不用爬起来手动编译固件了。Runner 会自动完成这些工作第二天上班直接测试最新固件就行。2. 为什么选择自托管 Runner2.1 嵌入式开发的特殊需求嵌入式开发有几个特点决定了我们需要自托管 Runner工具链复杂MDK、IAR 这些开发环境动辄几个GB云端 Runner 很难预装硬件依赖有些项目需要连接实际硬件进行测试网络限制很多开发环境在内网无法使用公有云服务我遇到过最头疼的情况是项目需要使用特定版本的编译器而云端 Runner 根本不支持。自托管 Runner 让你完全掌控环境想装什么就装什么。2.2 与 GitHub Actions 的对比虽然语法兼容但 Gitea Actions 有几个独特优势完全私有化代码和 CI/CD 流程都在自己服务器上资源零成本利用现有开发机作为 Runner不用额外付费定制灵活可以针对特定硬件做深度优化去年我们一个军工项目就因为数据安全要求必须使用自托管方案Gitea Runner 成了唯一选择。3. Windows 环境部署实战3.1 准备工作在开始前确保你的 Windows 开发机上有PowerShell 5.1 或更新版本已安装 MDK/IAR 等开发环境至少 2GB 可用磁盘空间用于工作目录建议专门创建一个英文路径的文件夹存放 Runner比如D:\gitea_runner。中文路径可能会导致一些奇怪的问题这是我踩过的坑。3.2 详细安装步骤下载 Runner 程序 从 Gitea 官方仓库下载对应版本嵌入式开发通常选择 Windows AMD64 版本。生成配置文件 在 PowerShell 中执行.\act_runner-windows-amd64.exe generate-config config.yaml关键配置项labels: [mdk] # 这个标签后面会用到 workdir_parent: D:\gitea_workdir # 工作目录路径注册 Runner.\act_runner-windows-amd64.exe register --config config.yaml --no-interactive --instance http://你的gitea地址 --token 你的token启动 Runner.\act_runner-windows-amd64.exe daemon --config config.yaml建议把这个命令做成 Windows 服务实现开机自启动。具体方法可以搜索nssm 创建 Windows 服务。4. 嵌入式工作流设计技巧4.1 基础工作流示例这是一个典型的 MDK 项目自动化编译工作流name: MDK Auto Build on: [push] jobs: build: runs-on: mdk # 对应 Runner 的标签 steps: - name: Checkout uses: actions/checkoutv3 - name: Build Project run: | call D:\Keil_v5\UV4\UV4.exe -j0 -b .\project.uvprojx if not exist .\Output mkdir Output copy .\project\*.hex .\Output\ - name: Upload Artifacts uses: actions/upload-artifactv3 with: name: firmware path: .\Output\*这个工作流做了三件事拉取最新代码调用 MDK 命令行编译打包输出固件4.2 高级技巧多环境构建如果你的项目需要支持多种芯片型号可以这样优化jobs: build: strategy: matrix: device: [N32G45x, STM32F103, GD32E230] runs-on: mdk steps: - name: Build for ${{ matrix.device }} run: | uv4.exe -j0 -b .\project_${{ matrix.device }}.uvprojx这样一次推送可以自动为所有型号生成固件特别适合产品线丰富的项目。5. 常见问题解决方案5.1 网络问题处理由于众所周知的原因直接使用 GitHub 的 Action 可能会失败。解决方法使用本地镜像 把actions/checkout等常用 Action 镜像到自己的 Gitea 实例修改工作流引用- uses: your_gitea/actions/checkoutmain5.2 依赖管理技巧嵌入式项目经常需要特定版本的库建议使用 git submodule 管理第三方库在工作流中添加初始化步骤- name: Init Submodules run: git submodule update --init --recursive5.3 调试技巧当工作流失败时查看详细日志本地复现问题在 Runner 的工作目录中找到对应的代码手动执行命令使用act工具本地调试需要安装 Docker6. 性能优化建议6.1 缓存策略重复下载依赖很耗时可以使用缓存- name: Cache Libraries uses: actions/cachev3 with: path: | .\libs .\Drivers key: ${{ runner.os }}-libs-${{ hashFiles(libs/**) }}6.2 并行构建对于大型项目拆分模块为独立工程使用矩阵策略并行构建最后合并结果6.3 资源监控在 config.yaml 中添加cache: enabled: true dir: D:\gitea_cache这样可以避免重复下载依赖提升构建速度。7. 安全最佳实践使用专用账户 为 Runner 创建低权限的 Windows 账户定期清理 在工作流中添加清理步骤- name: Clean Up run: | del /f /q *.obj del /f /q *.lst敏感信息处理 使用 Gitea 的 Secrets 功能存储证书、密码等- name: Flash Device run: | pyocd flash -t ${{ secrets.TARGET }} .\firmware.hex8. 扩展应用场景除了基础编译还可以实现自动化测试 连接实际硬件运行单元测试持续部署 通过 SWD/JTAG 自动烧录固件文档生成 使用 Doxygen 自动生成 API 文档静态检查 集成 cppcheck 等工具进行代码质量分析我在一个物联网项目中实现了完整的 CI/CD 流水线代码推送触发构建自动运行单元测试通过 OTA 推送到测试设备收集设备日志进行分析整个过程完全自动化大大提升了开发效率。