Usage for CI/CD

When using a GitHub or GitLab repo you can use KiBot to generate all the needed stuff each time you commit a change to the schematic and/or PCB file.

If you want a quick demo of what KiBot can do on a GitHub project try the following workflow. You just need to enable GitHub workflows and copy this workflow to your .github/workflows/ folder. In this mode KiBot will detect the project files, create a configuration and generate the targets. This workflow collects the generated files in Automatic_outputs.zip.

Examples of how to use KiBot can be found here for GitHub and here for GitLab.

In order to run KiBot on these environments you need a lot of software installed. The usual mechanism to achieve this is using docker. Docker images containing KiBot, all the supporting scripts and a corresponding KiCad can be found in the kicad5_auto, kicad6_auto, kicad7_auto and kicad8_auto GitHub packages. More complete images, with Pandoc, LaTeX, Blender and testing tools, can be found in the following packages: kicad5_auto_full, kicad6_auto_full, kicad7_auto_full and kicad8_auto_full GitHub packages. Old images can be found at Docker Hub as setsoft/kicad_auto and setsoft/kicad_auto_test.

The images are based on kicad5_debian, kicad6_debian, kicad7_debian and kicad8_debian. (setsoft/kicad_debian on Docker Hub), containing KiCad on Debian GNU/Linux.

If you need to run the current development version of KiBot you can use the following docker images: ghcr.io/inti-cmnb/kicad5_auto_full:dev, ghcr.io/inti-cmnb/kicad6_auto_full:dev, ghcr.io/inti-cmnb/kicad7_auto_full:dev or ghcr.io/inti-cmnb/kicad8_auto_full:dev (setsoft/kicad_auto:dev). These images are based on the full (also named test) images.

The most important images are:

Name	KiBot	KiCad
ghcr.io/inti-cmnb/kicad5_auto_full:latest	last release	5.1.9
ghcr.io/inti-cmnb/kicad6_auto_full:latest	last release	6.0.11
ghcr.io/inti-cmnb/kicad7_auto_full:latest	last release	7.0.11
ghcr.io/inti-cmnb/kicad8_auto_full:latest	last release	8.x
ghcr.io/inti-cmnb/kicad5_auto:latest	last release	5.1.9
ghcr.io/inti-cmnb/kicad6_auto:latest	last release	6.0.11
ghcr.io/inti-cmnb/kicad7_auto:latest	last release	7.0.11
ghcr.io/inti-cmnb/kicad8_auto:latest	last release	8.x
ghcr.io/inti-cmnb/kicad5_auto_full:dev	git code	5.1.9
ghcr.io/inti-cmnb/kicad6_auto_full:dev	git code	6.0.11
ghcr.io/inti-cmnb/kicad7_auto_full:dev	git code	7.0.11
ghcr.io/inti-cmnb/kicad8_auto_full:dev	git code	8.x
ghcr.io/inti-cmnb/kicad5_auto_full:1.6.5	1.6.5	5.1.9
ghcr.io/inti-cmnb/kicad6_auto_full:1.6.5	1.6.5	6.0.11
ghcr.io/inti-cmnb/kicad7_auto_full:1.6.5	1.6.5	7.0.11
ghcr.io/inti-cmnb/kicad8_auto_full:1.6.5	1.6.5	8.0.1
ghcr.io/inti-cmnb/kicad5_auto_full:1.6.4	1.6.4	5.1.9
ghcr.io/inti-cmnb/kicad6_auto_full:1.6.4	1.6.4	6.0.11
ghcr.io/inti-cmnb/kicad7_auto_full:1.6.4	1.6.4	7.0.11
ghcr.io/inti-cmnb/kicad5_auto_full:1.6.3	1.6.3	5.1.9
ghcr.io/inti-cmnb/kicad6_auto_full:1.6.3	1.6.3	6.0.11
ghcr.io/inti-cmnb/kicad7_auto_full:1.6.3	1.6.3	7.0.10
ghcr.io/inti-cmnb/kicad5_auto_full:1.6.2	1.6.2	5.1.9
ghcr.io/inti-cmnb/kicad6_auto_full:1.6.2	1.6.2	6.0.11
ghcr.io/inti-cmnb/kicad7_auto_full:1.6.2	1.6.2	7.0.5.1
ghcr.io/inti-cmnb/kicad5_auto_full:1.6.1	1.6.1	5.1.9
ghcr.io/inti-cmnb/kicad6_auto_full:1.6.1	1.6.1	6.0.11
ghcr.io/inti-cmnb/kicad7_auto_full:1.6.1	1.6.1	7.0.2.1
ghcr.io/inti-cmnb/kicad5_auto_full:1.6.0	1.6.0	5.1.9
ghcr.io/inti-cmnb/kicad6_auto_full:1.6.0	1.6.0	6.0.10
ghcr.io/inti-cmnb/kicad5_auto_full:1.5.1	1.5.1	5.1.9
ghcr.io/inti-cmnb/kicad6_auto_full:1.5.1	1.5.1	6.0.10
ghcr.io/inti-cmnb/kicad5_auto_full:1.4.0	1.4.0	5.1.9
ghcr.io/inti-cmnb/kicad6_auto_full:1.4.0	1.4.0	6.0.9
ghcr.io/inti-cmnb/kicad5_auto_full:1.3.0	1.3.0	5.1.9
ghcr.io/inti-cmnb/kicad6_auto_full:1.3.0	1.3.0	6.0.7
ghcr.io/inti-cmnb/kicad5_auto:1.2.0	1.2.0	5.1.9
ghcr.io/inti-cmnb/kicad6_auto:1.2.0	1.2.0	6.0.5

For more information about the docker images visit kicad_debian and kicad_auto.

GitHub workflows

A work-in-progress guide can be found here.

Usage of GitHub Actions

Note: You can also use –quick-start functionality with GitHub actions, an example is this workflow. This is the fastest way to test KiBot functionality.

You need to put a config.kibot.yaml file into the KiCad project folder.

Here is an example of workflow file using the GitHub Action:

name: example

on:
  push:
    paths:
    - '**.sch'
    - '**.kicad_pcb'
  pull_request:
    paths:
      - '**.sch'
      - '**.kicad_pcb'

jobs:
  example:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: INTI-CMNB/KiBot@v2
      with:
        # Required - kibot config file
        config: config.kibot.yaml
        # optional - prefix to output defined in config
        dir: output
        # optional - schematic file
        schema: 'schematic.sch'
        # optional - PCB design file
        board: 'pcb.kicad_pcb'
    - name: upload results
      uses: actions/upload-artifact@v2
      with:
        name: output
        path: output

For KiCad 6 use v2_k6 instead of v2 (v2_k7 for KiCad 7 or v2_k8 for KiCad 8). These actions use the last KiBot stable release, to use the current development code use v2_dk6 (KiCad 6) and v2_d (KiCad 5).

A working example applied to a repo can be found here (spora_main.yml). Another example, but using variants can be found here (kibot_action.yml for KiCad 7, kibot_action.yml for KiCad 5)

The available options are:

additional_args: Additional text to add to the KiBot invocation. This is intended for advanced use, report problems.
cache3D: When YES you can cache the downloaded 3D models. An example can be found here.
config: The KiBot config file to use. The first file that matches *.kibot.yaml is used when omitted.
dir: Output directory for the generated files. The current directory is used when omitted.
board: Name of the PCB file. The first file that matches *.kicad_pcb is used when omitted.
install3D: When YES installs the KiCad 3D models. Note that this will download more than 360 MiB and install more than 5 GiB of files.
quickstart: When YES ignores all the other options and runs in --quick-start mode. No configuration needed.
schema: Name of the schematic file. The first file that matches *.*sch is used when omitted.
skip: Skip preflights, comma separated or all. Nothing is skipped when omitted.
targets: List of targets to generate separated by spaces. To only run preflights use NONE. All targets are generated when omitted.
variant: Global variant to use. No variant is applied when omitted.
verbose: Level of verbosity. Valid values are 0, 1, 2 or 3. Default is 0.

GitHub Actions tags

There are several tags you can choose:

Tag	API	KiBot	KiCad
v1	1	1.2.0	5.1.9
v1_k6	1	1.2.0	6.0.5
v2_1_2_0	2	1.2.0	5.1.9
v2_k6_1_2_0	2	1.2.0	6.0.5
v2_1_3_0	2	1.3.0	5.1.9
v2_k6_1_3_0	2	1.3.0	6.0.7
v2_1_4_0	2	1.4.0	5.1.9
v2_k6_1_4_0	2	1.4.0	6.0.9
v2_1_5_1	2	1.5.1	5.1.9
v2_k6_1_5_1	2	1.5.1	6.0.9
v2_1_6_0	2	1.6.0	5.1.9
v2_k6_1_6_0	2	1.6.0	6.0.9
v2_1_6_2	2	1.6.2	5.1.9
v2_k6_1_6_2	2	1.6.2	6.0.11
v2_k7_1_6_2	2	1.6.2	7.0.5.1
v2_1_6_3	2	1.6.3	5.1.9
v2_k6_1_6_3	2	1.6.3	6.0.11
v2_k7_1_6_3	2	1.6.3	7.0.10
v2_1_6_4	2	1.6.4	5.1.9
v2_k6_1_6_4	2	1.6.4	6.0.11
v2_k7_1_6_4	2	1.6.4	7.0.11
v2_1_6_5	2	1.6.5	5.1.9
v2_k6_1_6_5	2	1.6.5	6.0.11
v2_k7_1_6_5	2	1.6.5	7.0.11
v2_k8_1_6_5	2	1.6.5	8.0.1
v2	2	last release	5.1.9
v2_k6	2	last release	6.0.11
v2_k7	2	last release	7.0.11
v2_k8	2	last release	8.x
v2_d	2	git code	5.1.9
v2_dk6	2	git code	6.0.11
v2_dk7	2	git code	7.0.11
v2_dk8	2	git code	8.x

The main differences between API 1 and 2 are:

API 2 adds support for variants and quick-start
In API 2 you can select which targets are created
In API 1 you must specify the input files, in API 2 can be omitted
API 1 supports wildcards in the filenames, API 2 doesn’t
API 2 supports spaces in the filenames, API 1 doesn’t

Also note that v2 images are currently using the full docker image (v1.5 and newer). It includes things like PanDoc and Blender.

GitHub Cache

GitHub offers a mechanism to cache data between runs. One interesting use is to make the KiCost prices cache persistent, here is an example

Another use is to cache downloaded 3D models