| path | File or directory to render. Passed verbatim as kicadiff's input
argument (project root, .kicad_pro, or a single KiCad file).
kicadiff's `--` separator only accepts one input, so multi-target
runs need separate action invocations. Default: cwd.
| no | . |
| from-ref | "before" git ref. Equivalent to kicadiff --from. Default:
github.event.pull_request.base.sha when inside a pull_request
event, else HEAD~1.
| no | "" |
| to-ref | "after" git ref. Equivalent to kicadiff --to. Empty string means
working tree. Default: github.event.pull_request.head.sha for
pull_request, else empty (working tree).
| no | "" |
| output-dir | Directory where images, HTML, and markdown are written. | no | kicadiff-output |
| kicad-version | KiCad major version to install from the official PPA on Linux. Empty
string skips the install step (useful when the runner already has
kicad-cli on PATH or when kicadiff is being driven against
pre-rendered output).
| no | 10 |
| install-kicadiff | How to obtain the kicadiff CLI:
- "bunx" : pull the latest published kicadiff on demand via
`bunx --bun kicadiff` (default — works for any
external consumer with no extra setup)
- "<ver>" : forced npm semver, e.g. "0.1.0", invoked as
`bunx --bun kicadiff@<ver>` (pin if you don't
want surprise upgrades)
- "skip" : assume `kicadiff` is already on PATH. Used by the
kicadiff repo's own dogfood workflow which
`pnpm install`s the source before invoking the
action.
| no | bunx |
| job-summary | "true" to write the structural diff and inline before/after images
to GITHUB_STEP_SUMMARY so it renders on the workflow run page
without any extra hosting. Defaults on (cheap and side-effect
free); set to "false" to skip.
| no | true |
| upload-artifact | "true" to upload the output directory as a build artifact (with
images, HTML, and markdown). Defaults off so the action stays
cheap when a caller only wants the inline summary.
| no | false |
| artifact-name | Artifact name. Empty string falls back to `kicadiff-pr-<num>`
inside a pull_request event, else `kicadiff-output`. Honoured
only when upload-artifact is true.
| no | "" |
| artifact-retention-days | How long the uploaded artifact is retained. The default (14 days)
covers most review cycles without keeping rendered PNGs around
forever. Honoured only when upload-artifact is true.
| no | 14 |
| pr-comment | "true" to upsert a sticky kicadiff comment on the PR, identified
by an HTML marker so successive runs replace it instead of
stacking. Requires the workflow to grant pull-requests: write and
to be running in a pull_request event. No-op outside a PR.
| no | false |
| pr-description | "true" to insert / update a kicadiff section in the PR description,
bracketed by HTML markers so author-written content outside the
block is preserved. Requires pull-requests: write. No-op outside
a PR.
| no | false |
| github-token | Token used for the gh CLI (PR comment / description upserts).
Defaults to the workflow's GITHUB_TOKEN.
| no | ${{ github.token }} |
| image-host | Where to put rendered images so they're reachable from the PR
comment / description as inline <img>:
- "artifact" (default): images live only in the build artifact;
the comment / description link to it for the rich view.
- "same-branch": copy combined before/after PNGs into the PR
head branch under `image-host-path`, commit + push them, and
embed `<img>` tags in the comment / description / job summary
via raw.githubusercontent.com so they render inline. Requires
contents: write on the workflow. Falls back to "artifact"
(with ::warning::) for fork PRs since GITHUB_TOKEN can't
push to forks.
| no | artifact |
| image-host-path | Project-relative directory where same-branch images are committed.
Honoured only when image-host is "same-branch".
| no | assets/kicadiff-preview |
| image-host-commit-message | Commit message for the auto-pushed image update. The action also
uses this as a marker to detect its own commits and skip the
heavy work on the synchronize event that the push triggers — so
changing it across runs would defeat the loop guard.
| no | chore(kicadiff): update preview images |