Giving Your KiCad PCB Repository Pretty Pictures

Screenshot of the GitHub Marketplace action listing, describing the extension

Publishing your boards on GitHub or GitLab is a must, and leads to wonderful outcomes in the hacker world. On their own, however, your board files might have the repo look a bit barren; having a picture or two in the README is the best. Making them yourself takes time – what if you could have it happen automatically? Enter kicad-render, a GitHub and GitLab integration for rendering your KiCad projects by [linalinn].

This integration makes your board pictures, top and bottom view, generated on every push into the repo – just embed two image links into your This integration is made possible thanks to the new option in KiCad 8’s kicad-cli – board image generation, and [linalinn]’s code makes KiCad run on GitHub/GitLab servers.

For even more bling, you can enable an option to generate a GIF that rotates your board, in the style of that one [arturo182] demo – in fact, this integration’s GIF code was borrowed from that script! Got a repository with many boards in one? There’s an option you could make work for yourself, too.

All you need to do is to follow a couple of simple steps; [linalinn] has documented both the GitHub and GitLab integration. We’ve recently talked about KiCad integrations in more detail, if you’re wondering what else your repository could be doing!

25 thoughts on “Giving Your KiCad PCB Repository Pretty Pictures

  1. Sadly, no, KiCad 8’s kicad-cli does not support rendering, this feature was only recently merged, so you either have to use 8.99 or wait until 9.0 releases next year.

  2. When I see Github “Marketplace” and “Actions” I immediately see my account suspended and emails demanding money.

    “If you want to use GitHub Actions beyond the storage or minutes included in your account, you will be billed for additional usage.”

    I dont see a way of blocking charges beyond free tier, ergo wont touch it.

      1. Things like this are always fine until they are not, aka AWS bill shock :(
        I rather not risk it in the first place if there is no way of blocking potential costs.
        Ill live with manually taking two crappy screenshots (, I need to crop and resize anyway :)

        It can definitely make more sense in large multi developer projects with multiple people pushing changes, but for a single hacker project why rely on github action instead of running locally as part of your git push script?

        1. With all due respect, you are missing the part where you don’t even have to link a credit card to use either GitHub or GitLab Actions, and you don’t have to choose the non-free tiers either. If you’re on a free tier and you somehow exceed the runtime, you can upgrade, but you don’t have to. This is the kind of thing you can set up and then have Just Work, without local generation and resulting “new images” binary (jpg) commits, uncluttering your git history a fair bit – that’s a big part of what makes Actions-driven generation so valuable.

          1. You are most likely right and Im just overthinking this based on my past (very bad) experience with AWS. After all they do state:

            “GitHub Actions usage is free for public repositories”

          2. Yeah I get the AWS shock, I have read dozens upon dozens of horror stories. That said, it’s not every company that does this, and GitHub/GitLab aren’t pushing you into it, as far as I’m aware. Also, didn’t even know about “free for public” part, thought it was the same limits for everyone – that’s nice!

          3. soo just tried it, and … its not zoomed in, half the image is empty background, so in the end resulting images need to be manually cropped anyway :(

  3. I don’t know about having github generate. Hopefully this doesn’t strain the resources. Would be nice to keep it a simple free service. Maybe let it generate on your side. Sounds small, until it ballons.

    1. It very much doesn’t strain the resources – the runtime is negligible! Also, yes, you can run this code locally, as it is with any action. The benefit here is that you don’t have to do .jpg (binary) file commit into your repo, and you can’t just forget to regenerate it or get tired of it, either.

    1. In my experience, the main problems with doing that are a) having to regenerate them after every commit, which takes time and you can easily forget about, and b) them being essentially binary files, which starts to bloat your repo real quick. I’d guess, these are the reasons why you won’t see most people storing them.

      1. Sure, then SVG instead of PDF to avoid binaries.
        Some common graphical format to make the content accessible, to avoid the necessity of installing every EDA tool just to peek at their project files.
        If generation were automatable, like this article emphasizes, that’s even better.

        1. only really applies to schematics, even then kinda – because svgs are large enough and non-reproducible enough (ala reproducible builds), you might as well consider them a binary file. also, doesn’t fix the gerber problem =( Having these generated and stored at the point of viewing, as opposed to the repo itself, seems to be ideal to me.

  4. linalinn kicad-render generates same file one gets when entering Kicad 3D Viewer. There is no control over Layers (turning off SMD Models), Raytracing, Zoom (broken default zoom-to-fit means 2/3 empty space) :( First two are not supported by kicad-cli so pass on that, but Zoom is. I tried to sneak zoom parameter inside pcb filename option “pcb_file: sram.kicad_pcb –zoom 2” but that didnt work, its not 2005 anymore :)

    It takes Github ~_2 minutes_ to render two measly screenshots, but surprisingly its not due to spinning huge heavy VM every time. Its much worse. Over 1 minute is spend in :
    “Pull down action image ‘’
    /usr/bin/docker pull
    nightly-2024-04-09-14-29: Pulling from linalinn/kicad-render
    bf4dc1c06610: Verifying Checksum
    bf4dc1c06610: Download complete
    4f4fb700ef54: Verifying Checksum
    4f4fb700ef54: Download complete
    b854ba985a25: Verifying Checksum
    b854ba985a25: Download complete
    Status: Downloaded newer image for”

    Yes, Github is pulling that huge heavy VM from linalinn repo every time Action is triggered. Its downloading and verifying same 2024-04-09 one month old build every time :o This is what corporate users are paying for, and this is what I was afraid of being charged for in my first comment. AWS bill shock due to Cloud being a fat joke :) You arent paying for actual Action, you are paying for inefficiencies and traps inherent in the system.

    All in all trying this made me hate cloud even more :)

    I downloaded kicad-nightly- to play with kicad-cli ‘pcb render’ locally. Its very new and immature :( Kicad blog suggests it was added just two months ago March 8. Cant even control layers right now (turn off SMD Models) :( Definitely not a substitute for manually exporting images from 3D Viewer precisely the way I like them (zoom, opengl, no smd components).

    1. That’s just how any action works – you have a Docker container with the environment set up for your work, and you run a pre-prepared script in that; this is not even going from linalinn repo, it’s going from, which is a general place you can publish your Docker images, so idk why it’s not cached. It’s up to GitHub/GitLab to cache them, is my understanding! But yeah, it does make for an inefficiency for sure. Also yeah, kicad_cli pcb render is new and not fully mature – it’s up for us to file bug reports/feature requests or contribute for anything that’s missing, I gather. That said, it’s the fastest way to render PCBs as-seen-in-KiCad, way faster than the pcbdraw method I’ve featured!

      1. I send linalinn patch adding controllable Zoom few days ago. I would do the same for controlling layers (turn off SMD Models) in kicad_cli, but gitlab wants my phone number (hilarious) to register :(

          1. “background” is optional and I copied that so I guess yes. It has some cleverness buildin for sure to reject my attempts at sneaking zoom inside filename. But Im not going to learn about building docker images for github actions just to check :-) Im sure linalinn will figure out how to fix it.

Leave a Reply

Please be kind and respectful to help make the comments section excellent. (Comment Policy)

This site uses Akismet to reduce spam. Learn how your comment data is processed.