The trust layer between KiCad commits and manufacturing release.
Local-first, policy-as-code hardware review gate for KiCad PCB teams. Explains what changed in every PR, why it matters for fabrication, and packages auditable release evidence. Manifests can be signed and verified when a signing key is configured.
Repository Maturity · OpenSSF Evidence · Governance · Roadmap · DeepWiki · Support
BoardReadyOps checks KiCad projects, can generate manufacturing artifacts, and packages findings and checksums into a release evidence bundle. Signing is optional; checksums and self-reported source fingerprints do not independently prove that the exported Gerber/Excellon files came from the reviewed commit. See the source-to-export provenance contract and issue #771. The CLI and GitHub Action support JSON, SARIF, Markdown, HTML, JUnit, and workflow annotation output.
- Does NOT replace KiCad DRC/ERC: Uses native
kicad-cliDRC/ERC checks alongside BOM lifecycle, footprint consistency, pinmap contracts, and vendor preflights. - Does NOT have to replace KiBot: Works standalone or alongside KiBot/artifact automation tools, adding governance, PR hardware diff, optionally signed evidence manifests, and handoff packages.
- Local-first source handling: CLI commands and target-repository GitHub Actions workflows process KiCad source in your own environment. Hosted features can retain run metadata, normalized findings, and links; review the documented data-handling and execution boundaries before enabling them.
Generate → Validate → Decide → Package → Optional Attestation → Review → Handoff
npm i -g boardreadyopsRepository-prepared version: boardreadyops@1.73.0. This is the package version
in this source revision, not evidence that it has been published.
Check npm and
GitHub Releases for the
latest publicly available version. Verify the selected release's binaries,
SHA256SUMS, SBOM, and runtime compatibility before installation. See
release channel verification
for historical verified snapshots and outstanding follow-ups.
BoardReadyOps supports Node.js 24 LTS only. Earlier Node major versions are no longer supported or CI-tested. Node.js 26 has entered upstream LTS, but remains unvalidated and unsupported in engines.node and CI until the dependency and cross-platform validation is completed.
KiCad CLI compatibility is CI-tested on KiCad 10.0, with 10.0.8 as the latest verified patch (native CLI netlist and PCB DRC smoke on 2026-11-03). KiCad 9.0 remains the minimum supported line but is upstream EOL and no longer CI-tested. The machine-readable policy and generated support table live in docs/support-matrix.md.
Linux and macOS release binaries are installed with the checksum-verifying shell
installer when the selected GitHub Release includes the matching binary asset
and SHA256SUMS:
curl -fsSL https://raw.githubusercontent.com/oaslananka/boardreadyops/main/install.sh | shWindows x64 release binaries use the same release asset and checksum flow:
irm https://raw.githubusercontent.com/oaslananka/boardreadyops/main/install.ps1 | iexThe installers download the release asset plus SHA256SUMS before placing
boardreadyops on the local command path. Binary asset availability depends on
the release; check the latest release
for the current asset matrix. A Homebrew
formula template for the same binary assets lives at Formula/boardreadyops.rb;
it is populated with published macOS and Linux checksums from SHA256SUMS.
The installers have been verified against the latest release which includes
the full binary matrix, SHA256SUMS, and SBOM. Tap publication remains a
maintainer follow-up.
BoardReadyOps provides two usage modes:
End-to-end pipeline — use boardreadyops generate to produce Gerbers, drill files, BOMs, CPL/position files, and PDFs via kicad-cli, then boardreadyops release prepare to validate, package evidence, and emit a signed release decision.
Validation-only gate — use KiBot or another generator to produce fabrication outputs, then use BoardReadyOps to validate those outputs exist, match the KiCad project, satisfy vendor/profile expectations, and can support a repeatable release decision.
See Release readiness and KiBot integration for the pipeline split approach, and the roadmap for v2 features.
# Validate existing manufacturing outputs
boardreadyops check .
boardreadyops plan . --format json > build/agent-plan.json
# Generate artifacts and prepare a full release
boardreadyops generate . --profile jlcpcb
boardreadyops release prepare . --profile jlcpcb --output build/release
# Verify a release bundle and create a vendor handoff package
boardreadyops release verify build/release
boardreadyops handoff create build/release --profile jlcpcb
# Optional: export actual Gerber/Excellon bytes as an unsigned, locally verified ZIP
# Requires KiCad CLI 10, exactly one PCB project and a clean checkout; ignore build/ in Git
boardreadyops release archive . --reviewed-source-sha "$(git rev-parse HEAD)"The release archive command verifies local source and output bytes and reports the resulting ZIP checksum. It does not produce a trusted workflow attestation, a cryptographic signature, vendor sign-off, or a cloud delivery link.
npx boardreadyops --help also works when npm can resolve the package.
name: BoardReadyOps
on:
pull_request:
push:
branches: [main]
jobs:
boardreadyops:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
security-events: write
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- uses: oaslananka/boardreadyops@9bc8a075d885ad1182e2ad4fcd4c9160f8160c94 # v1.31.2
with:
config: boardreadyops.yml
mode: enforce
fail-on: highThe examples pin the reviewed v1.31.2 release commit for reproducibility.
The floating v1 alias is convenient for opt-in automatic minor/patch updates,
but it moves as stable releases are published.
SARIF upload requires security-events: write. Pull request comments require pull-requests: write.
Use the full container action when a workflow should carry KiCad CLI inside the BoardReadyOps runtime instead of installing KiCad separately:
- uses: oaslananka/boardreadyops/apps/container@9bc8a075d885ad1182e2ad4fcd4c9160f8160c94 # v1.31.2
with:
config: boardreadyops.yml
require-kicad: "true"
mode: enforceThe same image can run as a CLI:
docker run --rm ghcr.io/oaslananka/boardreadyops-full:v1 --helpThe v1 and latest container tags resolve to the most recent release
image. Check the release channel verification
for the current digest and manifest list.
Explore the checked-in golden demo source before connecting a repository. The broken board has five findings and blocks release; the fixed board resolves them.
boardreadyops run examples/golden-demo/broken
boardreadyops run examples/golden-demo/fixedThese are reproducible source fixtures, not externally hosted pull requests. See the golden demo walkthrough for the expected evidence and decisions.
boardreadyops run --json build/findings.json --sarif build/findings.sarif.json .
boardreadyops check .
boardreadyops check manufacturing.jobset-outputs .
boardreadyops plan . --format json
boardreadyops doctor
boardreadyops schema configboardreadyops plan is the machine-readable workflow for coding and hardware agents. It emits JSON actions with finding evidence, fix steps, safe-auto-fix flags, and verification commands so agents can repair KiCad, BOM, pinmap, manufacturing-output, or release metadata issues without scraping human reports. See Agent Planning Output.
The npm package exposes the boardreadyops binary from the committed CLI bundle in dist/cli/index.cjs.
Create boardreadyops.yml:
version: 1
mode: warn
projects:
- path: .
pinmap: firmware/pins.yml
bom: bom/board.csv
variants:
- name: production
bom: bom/prod.csv
rules:
bom.missing-mpn:
enabled: true
severity: high
ignore-refs: ["TP*", "FID*"]
bom.variant-consistency:
enabled: true
manufacturing.jobset-outputs:
enabled: true
manufacturing.outputs-present:
enabled: true
required: [gerber, drill, position, pdf]
fail-on: high
report:
sarif: build/boardreadyops.sarif.json
json: build/boardreadyops.findings.json
markdown: build/boardreadyops.report.md
html: build/boardreadyops.report.htmlThe config schema is committed at schemas/config.schema.json.
- KiCad DRC and ERC report normalization.
- BOM completeness, lifecycle, DNP consistency, variant consistency, and footprint mismatch checks.
- Pinmap format, collision, unmapped pin, and net label checks.
- Manufacturing output, drill coverage, fab note, panel sanity, layer stackup, and jobset checks.
- Design outline and copper balance checks.
- Release revision, version format, tag, and changelog checks.
corepack pnpm install --frozen-lockfile
corepack pnpm run lint
corepack pnpm run typecheck
corepack pnpm run test
corepack pnpm run build
corepack pnpm run verify:dist
corepack pnpm run docsThe repository intentionally versions dist/action/index.cjs and dist/cli/index.cjs so the GitHub Action and npm package can run without a consumer build step.
BoardReadyOps is evolving from a validation gate into a full hardware release OS. See docs/ROADMAP.md for the milestone plan, the Public Roadmap Project for current execution, and issue #191 for roadmap sequencing.
- Repository: https://github.com/oaslananka/boardreadyops
- Issues: https://github.com/oaslananka/boardreadyops/issues
- Public Roadmap: https://github.com/users/oaslananka/projects/21
- Roadmap sequencing: #191
- Security advisories: https://github.com/oaslananka/boardreadyops/security/advisories/new
Current project-authored source is licensed under GNU AGPL v3.0, which permits commercial use under its terms. See Licensing for third-party and historical notices.
Third-party notices are generated in NOTICE. The full container image redistributes KiCad under its applicable GPL terms and preserves the KiCad license text inside the image.