GitHub Light Box

5 minute read

The GitHub Light Box, a real world alert for REVIEW, MERGE, PULL

Review Green Review Yellow Review Red
A box that lights up with GitHub status

This project has a lot of firsts for me.

First use of…

  • … laser cutter / engraver
  • … the GitHub API
  • … OpenAPI for a software project
  • … FastLED to control a WS2812 strip

The hardware models as well as the software are all available on GitHub

My problem with GitHub notifications

One of my personal goals this year is to be more responsive in my collaborations on GitHub. In particular the three shortcomings I want to address are:

  • I don’t want others pointing out that there is a pull request waiting for my REVIEW.
  • When my PRs are reviewed and ready for MERGE, I want to get them merged right away.
  • When a branch I have checked out locally if out of date, I want to PULL the updates right away so that I’m not making out of date branches.

So the three issues come down to being aware when I need to perform the actions of REVIEW, MERGE, and PULL. While I get notifications for the first two in slack and email, I find that they are lost in a sea of other notifications, and it isn’t always clear if my actions is still needed when I see the notice. As an example, I might get an email at 10 PM, but when I read it at 7 AM, someone else has already done the REVIEW and my input is no longer needed.

I could make a point of diligently checking GitHub, but that still means it can be hours before I realize something needs to be done, and I need to do it twice since I have two GitHub personas.

The REVIEW, MERGE, PULL light box

My solution is a physical world box.

All Lights
All sections lit

When there is no work to be done the lights are all off. When a fresh PR comes in the REVIEW light will turn green. As the PR gets older and unaddressed the colors moves through yellow to red. If the PR is approved by someone else it will turn off. Of course there can be many PRs spread across many repositories. So the color is based off the oldest unaddressed PR.

The same is true of the MERGE light. If I am the one that opened the PR, and it has been reviewed and approved, then it will start at green. The color will then move through yellow and red as I fail to merge the PR.

For the PULL light I went slightly different. If I need to PULL a commit then the light will turn a dim blue. As more commits need to be pulled the blue brightens and then eventually turns green, then yellow, and then red.

The build

For Christmas, I got a laser cutter/engraver. Other than some test pieces and learning at a local maker space, this was my very first laser cut project. I ended up making the physical aspect of this project twice. First with 6mm wood, where I learned a lot of design mistakes and pushed through until I got to a final prototype that worked and had lots of manual fixes for design failures. Then I took the lessons I learned and made a 3mm version.

I started with a simple 5 sided box from the generator, and then took the generated file and added the cuts for the letters, two plates to divide the box into thirds and prevent light from one line bleeding into the next.

The diffuser was also cut from parchment paper using the laser cutter. A 3D printed ring holds it in place.

Dividers are glued into the box to hold the diffuser and ring in place. These are spaced using a 3D back plane which will eventually hold the LED strip segments.

I dusted off the soldering iron for the first time in years, and connected the segments. While they did have an adhesive backing it would not stick to the PLA black plane, so I ended up gluing them and clamping them into place.

Once dry the backplane is then inserted back into the box, along with a small 3D printed shim to hold the microcontroller. It fits solely by friction so I can disassemble it when needed. The backplane also has a loop to hang the box when complete.

Prototype vs Final Laser Cut Diagram Parts Glued Install Diffuser Install Diffuser Ring Install Dividers Install LED segments Completed Back Plane Assembly
Assembly of the box

The Software

The software was a learning experience for me and was mostly written in rush over a weekend while learning how to use FastLED across multiple boards and while learning OpenAPI for Go. While the desired result has been achieved, I can already see a lot of changes I would want to make.

Software Diagram
Software Diagram


The sketch is pretty straight forward. It opens a UDP port on the embedded WIFI to accept updates. I started by allowing each line to be set individually, but as the software developed this turned out to be a problem. It required careful timing of the UDP packets and in some cases they would be dropped.

I originally developed this on an Arduino R4, but to get it to fit and be cheap I moved to a cheap ESP8266 board that I found. The FastLED implementation on this board required called twice in a row for the light changes to properly take effect.


The LightServer is an OpenAPI based server that accepts reports of items that need a REVIEW, MERGE, or PULL as well as the age of the item and some basic information. Each client provides a unique ID, so that when that client reports any previous reports are cleared. That way the clients do not need to track and clear what has been previously reported.

There is also an API for resetting the current list of items, as well as fetching them. At some point in the future I will probably add a GUI app to query the server to make it easier to zero in on what needs to be pulled. For now I am using the API directly with curl from the command line.


There are three clients that report to the LightServer. The first uses the GitHub API to search for PRs. The second uses the command line “gh” tool to do the same. These two clients and the LightServer run on a spare MacMini that I have in my home server closet.

The third client monitors my checked out repositories. It checks to see if there are any new commits on the origin and if so fetches them and then reports the need for the pull.