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:

Capabilities

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:

Development & required checks

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

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