boardreadyops

BoardReadyOps

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 binds every release to auditable, cryptographically verifiable evidence.

Repository Maturity · OpenSSF Evidence · Governance · Roadmap · Support

BoardReadyOps turns a KiCad project into a verified, signed, manufacturer-ready release package. It generates manufacturing artifacts, validates release readiness, packages evidence, and produces a clear release decision — running locally as a CLI and in CI as a GitHub Action, with JSON, SARIF, Markdown, HTML, JUnit, and workflow annotation output.

• Does NOT replace KiCad DRC/ERC: Uses native kicad-cli DRC/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, signed evidence manifests, and handoff packages.
• 100% Local-First & Zero-Trust: Designs and IP stay in your private workspace or GitHub runner. No schematics or source files are sent to external cloud servers.

Generate → Validate → Decide → Package → Attest → Review → Handoff

Installation

npm i -g boardreadyops

The current public npm package is boardreadyops@1.68.0. It is verified on Node.js 22.14+ and 24, includes the current CLI bundle, schemas, docs, Action metadata, and matches the public v1.68.0 tag archive. Binary release assets should be verified against v1.68.0, which publishes the current Linux, macOS, and Windows binary matrix, SHA256SUMS, and SBOM release assets. See release channel verification for the tested artifact list and remaining channel follow-ups.

Runtime Support

BoardReadyOps supports Node.js 22.14+ and 24. Node.js 24 is the recommended Active LTS runtime; Node.js 22.14+ remains supported for Maintenance LTS users. Node.js 26 Current is tracked but not supported in engines.node or CI until it reaches LTS and dependency validation is added.

KiCad CLI compatibility is CI-tested on KiCad 10.0, with 10.0.6 as the latest verified patch. 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.

Install Via Script

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 | sh

Windows x64 release binaries use the same release asset and checksum flow:

irm https://raw.githubusercontent.com/oaslananka/boardreadyops/main/install.ps1 | iex

The 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.

Positioning

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.

Quick Start

# 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

npx boardreadyops --help also works when npm can resolve the package.

GitHub Action

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: high

The 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: enforce

The same image can run as a CLI:

docker run --rm ghcr.io/oaslananka/boardreadyops-full:v1 --help

The v1 and latest container tags resolve to the most recent release image. Check the release channel verification for the current digest and manifest list.

Live demos

• A board that gets fixed — a blocked baseline, and the pull request that closes all five findings. The check goes green.
• A board that gets broken — a clean baseline, and a pull request that reads as routine housekeeping and makes the board unfabricable. The check goes red and says why.

Both are public and run the published Action, so you can read the findings, the sticky comment, and the fabrication diff without installing anything. The hardware is synthetic, so there is no customer data or secret to worry about. See the golden demo walkthrough.

CLI

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 config

boardreadyops 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.

Configuration

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.html

The config schema is committed at schemas/config.schema.json.

Supported Checks

• 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.

Local Development

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 docs

The 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.

Roadmap

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.

Links

• Repository: https://github.com/oaslananka/boardreadyops
• Issues: https://github.com/oaslananka/boardreadyops/issues
• Public Roadmap: https://github.com/users/oaslananka/projects/21
• Roadmap sequencing: https://github.com/oaslananka/boardreadyops/issues/191
• Security advisories: https://github.com/oaslananka/boardreadyops/security/advisories/new

License

Current project-authored source is licensed under PolyForm Noncommercial 1.0.0. Commercial use requires a separate written license; see Commercial Licensing. Earlier MIT releases retain the MIT rights that applied when they were published; see Licensing.

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.