How to Create a CI/CD Pipeline for Your PCB Design
At Altium Live 2019 (San Diego), I gave a talk with David Haboud on software development techniques for PCB design. This talk demonstrated what a Continuous Integration/Continuous Delivery (CI/CD) pipeline would look like within a DevOps environment. In that talk I used the Atlassian tool suite (Jira, Bitbucket, and Bamboo) to create my DevOps flow for PCB design. In this article, I am going to demonstrate and provide a full CI/CD project example using Gitlab, which offers a free Git server with built-in CI/CD capability.
Before you create (or clone) a project, you will need to sign up for a free Gitlab account. Additionally, in order to trigger builds to use Altium Designer, you will need to install a Gitlab Runner (i.e. agent) on your Windows machine, configure the runner with your project, then run it locally within a shell (versus a service). Exact details on how to get the runner working is beyond the scope of this article. For more information on getting set up with Gitlab, you can consult the Gitlab documentation. Note that these instructions are Gitlab specific, but the same process has been done with Jenkins and Atlassian Bamboo as well. After you’ve set up your agent, you should see a window that looks something like this:
In this article, we will review a simple CI/CD example using the SAM4E XPlained Pro evaluation board design from Microchip. In a future article we will use the same board to demonstrate hardware in the loop testing. The design files for this project can be found here on Gitlab. At the time of writing this article, the design files were hosted on Microchip’s website. The design files have been untouched with the exception of the OutJob file, which I modified for simpler scripting. Additionally, I have added a Delphi script, GenerateOutputFiles.pas, that runs the automation once Altium Designer is called from the agent. The .gitlab-ci.yml file is the pipeline definition that tells the agent what to do.
The flow for this project is rather simple. The designer works through the design (whether it be schematic capture, layout, etc.), commits that design to the server, and then has all the artifacts published by the agent. The next iteration of that cycle continues until you are ready to build your board. The following is an illustration of that pipeline:
The output files for this project contain multiple artifacts specified in the OutJob file.
We can view the artifacts generated by our agent within every build on the right side of the job status page:
Job #531015819, for example, contains fabrication data, assembly data, and other data packages for teammates (or in this case, customers) to review:
The key takeaway here is that anyone gets to review the original design files, generated packages, and track all issues in the same place (though the issue tracking/code storage/agent all-in-one solution is only provided by Gitlab (but can be extended to any other CI/CD setup). This now means that:
- Folks from the software team can now get the latest PDF version of the schematics.
- Manufacturing engineers can hold a DFM review of your latest package generation (that happens automatically by your agents on every commit).
- Mechanical engineers are getting the most up to date STEP file that is being generated from your PCB.
Everything now happens continuously and in the background without you ever lifting a finger. None of this should be new to you if you have read some of my previous articles, but this article gives you a concrete example for how to get this up and running. To summarize, here are the steps needed to create a full CI/CD pipeline:
- Sign up for a free Gitlab account.
- Configure a Gitlab Runner to run on your Windows machine (using cmd shell as the default versus Powershell).
- Fork the SAM4E XPlained Pro repository on Gitlab.
- Run the pipeline manually or via a commit and push to the repository.
- Watch your artifacts being generated.
- Bonus: Create an issue and refer to that issue number in your code commit (e.g. “First commit #3”) to watch the two link together.
In this article, we reviewed a working example of an Altium Designer project running through the CI/CD process. Through the use of Gitlab and its agent capabilities, we are able to automatically run OutJobs to generate our data packages upon every commit. This enables us to create packages, not only for review by our teammates, but also for our customers without the need for extra steps. A link to the repository has also been provided to the reader at the beginning and end of this article to try it out for themself. All that is needed is a free Gitlab account and a computer running Altium Designer.