x0f5c3/esp32-bus-pirate

# GitHub Actions 工作流 本目录包含 ESP32 Bus Pirate 项目的 CI/CD 流水线。 ## 工作流 ### [`ci.yml`](./workflows/ci.yml) **持续集成** - 在每次推送和拉取请求时运行 **任务：** - **check**：格式化并检查 Rust 代码 - **test**：运行单元测试和文档测试 - **build-docs**：构建 mdBook 文档 - **conventional-commits**：验证提交信息格式（仅限 PR） - **build-rust**：为 ESP32-S3 构建固件 - **status-check**：汇总所有任务的状态 **触发条件：** - 推送到 `main`、`develop` 或 `copilot/**` 分支 - 拉取请求到 `main` 或 `develop` ### [`deploy-docs.yml`](./workflows/deploy-docs.yml) **文档部署** - 将 mdBook 部署到 GitHub Pages **任务：** - **build**：使用 mdBook 和 mermaid 构建文档 - **deploy**：部署到 GitHub Pages **触发条件：** - 推送到 `main` 分支（当 `book/**` 发生变化时） - 手动工作流调度 **要求：** - 必须在仓库设置中启用 GitHub Pages - 设置为从 GitHub Actions 部署 ### [`release.yml`](./workflows/release.yml) **发布自动化** - 当推送标签时创建发布 **任务：** - **create-release**：使用 git-cliff 生成变更日志并创建 GitHub 发布 - **build-firmware**：为所有目标构建固件二进制文件 - **build-docs-release**：构建并附加文档 - **publish-crates**：将 crates 发布到 crates.io（可选） **触发条件：** - 匹配 `v*` 的标签（例如 `v1.0.0`） - 匹配 `release/v*` 的分支（用于发布准备） **创建发布：** ``` # 1. 更新 Cargo.toml 文件中的版本 # 2. 提交更改 git add . git commit -m "chore(release): prepare for v1.0.0" # 3. 创建并推送标签 git tag -a v1.0.0 -m "Release v1.0.0" git push origin v1.0.0 ``` ## 所需密钥 在仓库设置中配置以下密钥： - **`GITHUB_TOKEN`**：由 GitHub Actions 自动提供 - **`CARGO_REGISTRY_TOKEN`**：用于发布到 crates.io（可选） - 从 https://crates.io/settings/tokens 获取 - 添加到仓库密钥 ## 缓存策略 所有工作流均使用 GitHub Actions 缓存来加速构建： - **Cargo 注册表**：`~/.cargo/registry` - **Cargo Git**：`~/.cargo/git` - **构建产物**：`rust/target` 缓存键包含 `Cargo.lock` 哈希以实现自动失效。 ## 状态徽标 添加到 README.md： ```   ``` ## 监控 - **Actions 标签页**：查看所有工作流运行 - **拉取请求**：在合并前查看状态检查 - **发布**：自动创建并附带变更日志和构件 ## 故障排除 ### `cargo build` 工作流失败 检查： 1. 所有 `Cargo.toml` 文件包含正确的依赖项 2. `rust-toolchain.toml` 指定了正确的 Rust 版本 3. espup 安装成功 ### 文档部署失败 检查： 1. 已启用 GitHub Pages 2. 源设置为 "GitHub Actions" 3. `book/book.toml` 有效 4. 所有引用文件存在 ### 发布工作流未触发 检查： 1. 标签格式匹配 `v*`（例如 `v1.0.0`，而非 `1.0.0`） 2. 标签已推送到远程：`git push origin v1.0.0` 3. 工作流文件存在于创建标签的分支上 ## 本地测试 使用 [act](https://github.com/nektos/act) 本地测试工作流： ``` # 安装 act brew install act # macOS # 或 sudo apt install act # Linux # 运行 CI 工作流 act push # 运行特定作业 act -j check # 带密钥运行 act -s CARGO_REGISTRY_TOKEN=xxx ``` ## 自定义 ### 添加新任务 1. 编辑相应的工作流文件 2. 在 `jobs:` 部分下添加任务 3. 尽可能本地测试 4. 提交并推送到 GitHub 测试 ### 修改构建矩阵 编辑 `ci.yml` 或 `release.yml` 中的 `strategy.matrix`： ``` strategy: matrix: target: - xtensa-esp32s3-none-elf - xtensa-esp32-none-elf # Add ESP32 classic ``` ## 性能 - **平均 CI 时间**：约 5-10 分钟 - **缓存命中**：约 2-3 分钟 - **文档构建**：约 1 分钟 - **发布构建**：约 10-15 分钟 ## 相关链接 - [GitHub Actions 文档](https://docs.github.com/en/actions) - [Rust GitHub Actions](https://github.com/actions-rs) - [git-cliff 配置](../../cliff.toml)

标签：Bus Pirate, ESP32, GitHub Actions, GitHub Pages, mdBook, Rust, Web CLI, 协议工具, 单元测试, 可视化界面, 固件开发, 客户端加密, 嵌入式安全, 开源框架, 开源硬件, 持续集成, 文档构建, 文档测试, 格式校验, 版本发布, 物联网安全, 状态聚合, 电子开发, 硬件安全, 硬件黑客, 网络流量审计, 自动化发布, 自动笔记, 触发器