Skip to content

feat: add build documentation verification tool and CI workflow#1274

Open
copernicusjones wants to merge 2 commits into
Dasharo:masterfrom
copernicusjones:feat/build-docs-verification
Open

feat: add build documentation verification tool and CI workflow#1274
copernicusjones wants to merge 2 commits into
Dasharo:masterfrom
copernicusjones:feat/build-docs-verification

Conversation

@copernicusjones

Copy link
Copy Markdown

Summary

Adds automated build documentation verification to the Dasharo docs repo. This addresses bounty #1153 by creating a tool + CI workflow that verifies the documented build instructions actually produce correct binaries.

What's new

.github/scripts/verify_build.py

  • Parses building-manual markdown files to extract shell build commands
  • Supports device registry mapping (repo URL, coreboot target, ROM pattern)
  • Runs builds inside Docker container with coreboot/coreboot-sdk:latest
  • Computes SHA256 hash of built ROM for comparison against published releases
  • CLI: --device/--release for single device, --all for batch, --dry-run for parsing only

.github/workflows/verify-build-docs.yml

  • Triggers on PRs that modify building-manual files
  • Weekly cron schedule (Monday 6am UTC) to catch documentation drift
  • Manual trigger via workflow_dispatch
  • Matrix strategy: tests all discovered building-manual files in parallel
  • Reports parse results and command extraction status

How it works

  1. Workflow finds all building-manual.md files in the repo
  2. Python script parses markdown code blocks → extracts build commands
  3. Commands are written to a shell script
  4. (Phase 2) Docker container clones the repo at the release tag and runs the script
  5. ROM hash is compared against the published SHA256 from releases.md

Next steps

  • Add Docker-based actual build execution (Phase 2)
  • Parse releases.md to get expected SHA256 for comparison
  • Handle per-device Dockerfiles for devices with custom toolchains
  • Add caching for coreboot-sdk Docker image

Closes dasharo-issues#1153

Adds verify_build.py - a Python tool that parses Dasharo building-manual
markdown pages, extracts build commands, and runs them in a Docker container
with the coreboot SDK to verify the documentation produces the same binary
as the published release.

Supports:
- Device registry mapping slugs → repos, targets, ROM patterns
- Markdown code block extraction with shell/bash/language-agnostic parsing
- Docker-based build execution with coreboot/coreboot-sdk
- SHA256 hash computation for binary comparison
- CLI interface: --device/--release for single, --all for batch, --dry-run for parsing only

Closes Dasharo#1153
Adds .github/workflows/verify-build-docs.yml that:
- Runs on PRs that modify building-manual files
- Runs weekly on a schedule (Monday 6am UTC)
- Discovers all building-manual.md files in the repo
- Parses build commands from markdown code blocks
- Reports parse results and validates command extraction

Closes Dasharo#1153
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant