Meshtastic GitHub Action Runner 镜像文档

镜像概述

Meshtastic GitHub Action Runner 是专为Meshtastic项目设计的自托管GitHub Actions运行器镜像，基于Ubuntu LTS构建，预装Meshtastic开发全套依赖工具（Python、PlatformIO、meshtastic-cli等），用于自动化执行代码构建、固件编译、单元测试及部署等CI/CD任务，简化Meshtastic开发流程。

核心功能与特性

• 无缝集成GitHub Actions：支持注册为仓库/组织级运行器，自动接收并执行GitHub Actions工作流任务
• 预装开发依赖：内置Meshtastic开发必需工具链，包括Python 3.10+、PlatformIO Core、git、meshtastic-cli、USB设备驱动等，开箱即用
• 多架构支持：适配x86_64、ARMv7/ARM64等主流架构（需对应架构镜像版本）
• 灵活配置：支持自定义运行器名称、标签、工作目录及资源限制，适配不同场景需求
• 安全优化：最小化镜像体积，定期更新依赖组件以修复安全漏洞，支持临时运行器模式（任务结束自动注销）

使用场景

• 核心开发团队CI/CD：自动化执行Meshtastic设备固件的构建、多平台兼容性测试及正式版部署
• 社区贡献验证：为Pull Request提供自动化测试环境，快速验证代码变更的功能与稳定性
• 多设备固件编译：并行处理不同硬件平台（如ESP32、nRF52）的固件编译任务
• 文档与工具链同步：基于代码变更自动生成API文档并部署至Meshtastic***网站

使用方法与配置说明

前提条件

• GitHub账号及Meshtastic项目仓库访问权限（或自建仓库）
• 生成GitHub Personal Access Token（PAT），需包含repo和admin:org权限（用于注册运行器）
• Docker环境（Docker Engine 20.10+ 或 Docker Desktop）

快速启动（docker run）

bash
docker run -d \
  --name meshtastic-runner \
  -e GITHUB_TOKEN="your_github_pat" \
  -e RUNNER_REPOSITORY="meshtastic/Meshtastic-device" \
  -e RUNNER_NAME="meshtastic-ci-01" \
  -e RUNNER_LABELS="meshtastic,firmware-build,x86_64" \
  meshtastic/action-runner:latest

环境变量配置

Docker Compose配置示例

yaml
version: '3.8'
services:
  meshtastic-runner:
    image: meshtastic/action-runner:latest
    container_name: meshtastic-ci-runner
    restart: unless-stopped
    environment:
      - GITHUB_TOKEN=your_github_pat_here
      - RUNNER_REPOSITORY=meshtastic/Meshtastic-device
      - RUNNER_NAME=meshtastic-firmware-builder
      - RUNNER_LABELS=meshtastic,firmware-build,arm64
      - RUNNER_EPHEMERAL=true
    volumes:
      - runner-workdir:/_work  # 持久化工作目录，加速依赖缓存
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0  # 映射USB串口（如需固件烧录）
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G

volumes:
  runner-workdir:

运行器验证与管理

1. 验证运行状态：

   bash
   docker logs meshtastic-ci-runner
   

   成功注册日志示例：√ Runner registered successfully

2. GitHub仓库验证： 进入仓库 → Settings → Actions → Runners，查看运行器状态应为"在线"（Online）

3. 工作流触发示例： 在Meshtastic项目中创建.github/workflows/firmware-build.yml：

   yaml
   name: Build Firmware
   on: [push]
   jobs:
     build:
       runs-on: [self-hosted, meshtastic, firmware-build]
       steps:
         - uses: actions/checkout@v4
         - name: Build firmware
           run: pio run -e tbeam
   

停止与清理

bash
# 停止运行器
docker stop meshtastic-ci-runner

# 移除容器（临时模式下自动注销，非临时模式需手动注销）
docker rm meshtastic-ci-runner

# 清理工作目录（如需彻底重置）
docker volume rm runner-workdir

注意事项

• GITHUB_TOKEN需限制最小权限，建议仅授予必要仓库的repo权限，避免使用组织级管理员令牌
• 运行器标签需与工作流runs-on字段严格匹配（如[self-hosted, meshtastic]）
• 定期更新镜像（docker pull meshtastic/action-runner:latest）以获取依赖安全更新
• 生产环境建议使用Docker Secrets或环境变量文件注入敏感信息，避免明文传递GITHUB_TOKEN