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 implementing 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 as applied to PCB design projects. In that talk, I used the Atlassian tool suite (Jira, Bitbucket, and Bamboo) to create my DevOps flow for PCB design projects. 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.

What is GitLab and Why Use Git for Hardware Development?

If you're familiar with the history of Linux, then you probably know about Git. I won't get too deep into Linux, but it is important to know about Git and how it is being adapted to hardware development. Git is a software tool that makes it really easy to change, track, branch, and clone projects while enforcing version control and revision tracking. GitLab is a software development tool used for hosting and managing Git repositories, but it includes additional management features that help automate important tasks in DevOps. Some of the other built-in features are used for code reviews, issue tracking, streaming activity feeds, and hosting wikis.

Even though Git was developed for revision tracking and version control in software projects, it provides the same functions for anything that can be coded, including design documents for PCB projects. As more hardware teams are distributed geographically, tools like Git can be used to help keep PCB design teams organized and ensure revisions to projects are tracked, regardless of where everyone is located.

What I'll show now is how you can use a tool like GitLab in your team's PCB design processes. The goal is to show one way you can quickly implement an automated process that applies the same version control and revision tracking features used in software development to your hardware development projects. With more PCB designers working remotely, it's essential to add these features to your PCB design tools.

Configuration: GitLab

Before you create (or clone) a PCB 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). Like its name suggests, a GitLab Runner will "run", or execute, your project's GitLab CI jobs. Your "GitLab instance" is the GitLab service that hosts your projects and is identified with a URL.

What is a GitLab Runner? It is a worker machine that executes your project's GitLab CI jobs and continually sends requests to be assigned additional jobs. Runners form the core of GitLab instances and they can have different capabilities that a GitLab Runner administrator user can include in its configuration. To match your jobs to the right Runners, you have to tag your jobs as well; only Runners with all the same tags as a job will be eligible to execute that job. A Runner can be configured as specific (available to individually chosen projects), group (available to all projects in a group), or shared (available to every project in the GitLab instance).

Exact details on the process for getting a runner working are 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 can run it from a console window. You should see a window that looks something like this:

Design Files

In this article, we will review a simple CI/CD pipeline 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 from the original Microchip design files for simpler scripting.

Automation with GitLab

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. This script will be called by GitLab and will generate the output files from your project, at which point GitLab will add them to your organization's Git repository. Once the output files are in the repository, they become subject to version control; they can be instantly cloned, forked, rolled back to an earlier version, or shared by anyone with access to the repository.

Pipeline

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 output files (called "artifacts" in the Git world) 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 (artifacts ) for this project are the items 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. If I open this job in my GitLab UI, I'll see the following screen:

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:

1. Folks from the software team can now get the latest PDF version of the schematics.
2. Manufacturing engineers can hold a DFM review of your latest package generation (that happens automatically by your agents on every commit).
3. 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:

1. Sign up for a free GitLab account.
2. Configure a GitLab Runner to run on your Windows machine (using cmd shell as the default versus Powershell).
3. Fork the SAM4E XPlained Pro repository on GitLab.
4. Run the pipeline manually or via a commit and push to the repository.
5. Watch your artifacts being generated.
6. 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.

Conclusion: Use Altium 365 in Git for Hardware Development?

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 themselves.

If you're not a software developer, the Altium 365™ platform now gives every Altium Designer® user access to these same capabilities through a managed cloud platform. When you host your projects on Altium 365, your projects will be entered into a version control and revision tracking system for your organization, enabling collaboration and sharing with your design data. 

We have only scratched the surface of what is possible to do with Altium Designer on Altium 365. You can check the product page for a more in-depth feature description or one of the On-Demand Webinars.