kicad-bot

A CI quality gate for KiCad projects — ERC/DRC verification, BOM availability checks, visual diffs, and fabrication-output generation. CI-friendly and framework-agnostic.

kicad-bot runs your KiCad project through automated quality gates on every push and pull request, and produces a fabrication/documentation package on release. It catches electrical (ERC) and design-rule (DRC) violations before they reach main, flags BOM parts that have gone end-of-life or out of stock, generates visual schematic/PCB diffs for reviewers, and emits a reproducible fab package on tag — so the board that ships is always verified, sourceable, and reproducible.

It wraps battle-tested upstream tooling rather than reinventing it:

Tool	Used for
kicad-cli (KiCad 8+)	headless ERC/DRC (--exit-code-violations, --schematic-parity)
KiBot	fabrication/documentation output generation & orchestration
KiCost (via KiBot)	distributor-API pricing, availability, lifecycle status
KiDiff / KiBot diff	graphical schematic & PCB diffs

Capabilities

Capability	Action flag	CLI entry point	Backed by	Gates
Verify	run-verify	kicad-bot-verify	kicad-cli sch erc / pcb drc	fail-on-erc, fail-on-drc, drc-severity
BOM check	run-bom-check	kicad-bot-bom	KiBot + KiCost	fail-on-eol, fail-on-unavailable
Diff	run-diff	kicad-bot-diff	KiDiff / KiBot diff	(non-gating, informational)
Fabrication	run-fab	kicad-bot-fab	KiBot outputs	fail-on-missing-output
Quickstart	quickstart	kicad-bot-quickstart	auto-detect + run enabled stages	n/a

Quick start

name: kicad-bot
on:
  push:
    paths: ["**.kicad_sch", "**.kicad_pcb"]
  pull_request:
    paths: ["**.kicad_sch", "**.kicad_pcb"]

jobs:
  kicad-bot:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: embedded-pro/kicad-bot@v0
        with:
          run-verify: "true"
          fail-on-drc: "true"

Enabling more capabilities is just more flags:

      - uses: embedded-pro/kicad-bot@v0
        with:
          run-verify: "true"
          run-bom-check: "true"
          run-diff: "true"
          fail-on-drc: "true"
          fail-on-eol: "true"
          distributors: "Mouser,Digi-Key"
        env:
          MOUSER_KEY: ${{ secrets.MOUSER_KEY }}
          DIGIKEY_CLIENT_ID: ${{ secrets.DIGIKEY_CLIENT_ID }}
          DIGIKEY_CLIENT_SECRET: ${{ secrets.DIGIKEY_CLIENT_SECRET }}

Path filters keep kicad-bot from running on unrelated commits. Restrict the workflow to changes that touch **.kicad_sch / **.kicad_pcb as shown above.

Outputs

Each run writes to output-dir (default kicad-bot-output/) and uploads it as a build artifact:

File	Purpose
report.md	Full report: ERC/DRC summary, BOM table, diff thumbnails
pr_comment.md	Compact PR comment (idempotent marker)
kicad_bot_metrics.json	Machine-readable summary (counts, pass/fail per gate)
erc.json / drc.json	Raw kicad-cli JSON reports
bom.xlsx	KiCost spreadsheet (cost/availability/lifecycle) — with run-bom-check
diff.pdf	Schematic/PCB visual diff — with run-diff
fab/	Gerbers, drill, position, BOM, 3D, schematic PDF — with run-fab

Development & required checks

This repo's own CI (.github/workflows/ci.yml) runs three jobs you can mark as required status checks on main:

Job	What it guards
lint	ruff lint + format and mypy --strict
unit	hermetic unit tests on Python 3.11–3.13
integration	full kicad-bot-verify pipeline against the examples/ projects using a real kicad-cli

The integration job installs KiCad and runs tests/integration/, which verifies the clean examples/minimal project passes and the deliberately-broken examples/drc-violation project trips the DRC gate. Locally these tests skip automatically when kicad-cli is not installed, so pytest tests/unit stays fast and dependency-free.

All workflow actions are pinned to commit SHAs and kept current by Dependabot (.github/dependabot.yml).

Documentation

• Usage — every CLI flag and action input/output
• Config schema — the kicad-bot.json reference
• Capabilities — what verify / bom / diff / fab each do
• Secrets — distributor API key handling
• Architecture — internal module layout & data flow
• Troubleshooting — headless, fonts, common errors

Scope & limitations

• kicad-bot is a CI guardrail, not a substitute for design review or sign-off.
• BOM availability is a snapshot of distributor data at run time, not a guarantee of stock at order time.
• Visual diffs surface geometric/electrical changes but do not perform semantic net-level reasoning.
• Git remains unsuitable for merging concurrent board edits; kicad-bot verifies, it does not resolve layout conflicts.

License

Apache-2.0