View All Posts
Want to keep up to date with the latest posts and videos? Subscribe to the newsletter
HELP SUPPORT MY WORK: If you're feeling flush then please stop by Patreon Or you can make a one off donation via ko-fi

Learn how to add GitHub badges to your Arduino projects, improving project visibility and attracting contributors. Set up automated build checks with GitHub Actions to prevent broken code merges.

Related Content

[0:00] If you’ve ever browsed around projects on GitHub, you’ll have seen these nice badges.
[0:04] They provide a quick and easy way to show the current status of a project.
[0:07] Does the code build?
[0:08] What’s the test coverage percentage?
[0:10] What’s the latest release?
[0:11] They are really useful.
[0:12] Now, I know a lot of you will be thinking, my project is a simple Arduino sketch.
[0:17] What’s the point of this?
[0:18] Where are your badges?
[0:20] Badges?
[0:21] We ain’t got no badges.
[0:23] We don’t need no badges.
[0:25] I don’t have to show you any stinking badges.
[0:28] Well, my dear Bandito, I would strongly disagree.
[0:31] These badges are like stickers you put on the project to share important information about
[0:34] its health and progress.
[0:36] The help developers and non-developers quickly understand the project’s status and make
[0:40] informed decisions about whether to use or contribute to the project.
[0:44] If you have a badge, you are more likely to attract people to your project.
[0:47] There’s an added benefit that comes from adding these badges.
[0:51] Under the hood, your code is constantly being checked and compiled.
[0:54] Not only can this alert you to when you have pushed up broken code, but it can also prevent
[0:58] other people from breaking your project.
[1:00] The typical way that people contribute to your projects is via pull requests.
[1:04] You can easily set things up so that their code can only be merged if it actually builds.
[1:08] They will know if it fails and can fix it themselves, or without any involvement from you.
[1:13] So how does it work?
[1:14] It’s very simple.
[1:16] The badges and status checks are all driven off GitHub actions.
[1:19] To create an action, just create a folder called .github and create a folder within
[1:23] that called workflows.
[1:25] The Arduino guys have already done all the hard work for you and have some great documentation.
[1:30] And just look at all the build badges they have on their project.
[1:32] Here’s a very simple workflow that will build a sketch for an ESP32 project.
[1:37] Much of this is standard boilerplate for GitHub actions.
[1:41] We give our action a name, in this case I’ve just called it build_arduino_sketch, and we
[1:45] tell the action when it should run.
[1:47] I have set it up to run whenever someone pushes code to the repository.
[1:51] And then we tell it what jobs to run.
[1:52] We just have a build job.
[1:53] We tell it to use the latest version of Ubuntu, and then we tell it to check out the code.
[1:58] All of this is pretty standard GitHub workflow boilerplate.
[2:00] You can read their detailed documentation for more details.
[2:03] Finally, we have the code that builds the Arduino sketch.
[2:06] There’s a couple of bits here that do need some explanation.
[2:10] FQBN is the most tricky one.
[2:12] FQBN stands for Fully Qualified Board Name.
[2:15] It is comprised of the board’s core name, architecture and board identifier.
[2:19] For example, the FQBN for the Arduino UNO is Arduino colon AVR colon UNO, where Arduino
[2:26] is the core name, AVR is the architecture and UNO is the board identifier.
[2:32] It is pretty easy to get a complete list of all the FQBN values.
[2:36] You just need to make sure you have the Arduino command line interface installed.
[2:39] If you don’t have it, then you can easily install it from the official Arduino website.
[2:43] You then just run arduino-cli board listall.
[2:47] Now if your board isn’t listed, for example the ESP32 boards, do not come as standard, then
[2:52] you can simply add them by following the same steps you would use from the Arduino GUI.
[2:56] First you add the additional URL to the board manager, and then you update the board index,
[3:01] and then finally you install the ESP32 boards.
[3:05] Back in the github action, if your FQBN is not part of the standard install, then you
[3:09] need to add it to the platform section.
[3:11] In this example, we’re adding the ESP32 boards.
[3:15] The next important section is the list of libraries that your sketch needs.
[3:18] And then the final argument is the list of paths that contain sketches.
[3:22] It all sounds pretty complicated, but it really is very simple, and the actual file is only
[3:26] 20 or so lines long.
[3:28] With the file in place, you will now have a GitHub action that runs every time you push
[3:32] up changes to your repository.
[3:33] To get a nice build badge, simply go to the repository and select the actions tab.
[3:39] Select your action, and then click on the three dots.
[3:41] You can now copy and paste your badge code into your readme file.
[3:45] Let’s push up some broken code and see what happens.
[3:48] We can see the action kicks off, eventually it will fail with an error.
[3:51] If we go and check our email, we can see that we’ve got an alert telling us that it failed.
[3:55] And if we go to the main page of our repository, we can see that our badge is updated to failing.
[4:01] Let’s put up a fix, and get everything back to green.
[4:03] We push up the code, and we get a new build running.
[4:06] Once it’s finished, we can see we’ve got a green tick on the action, and back on the
[4:09] main screen, our badge is now updated, and we’re all green here as well.
[4:12] But what’s this?
[4:13] There’s a quick plug for the channel sponsor PCBWay.
[4:16] I wonder how that got there.
[4:17] We’ve had a bunch of PCBs made by them, and they are really great.
[4:21] Check out our link to them in the description of the video.
[4:23] You will love working with them.
[4:24] The last thing that I recommend is setting up things so that pull requests can only be
[4:28] merged if the GitHub action passes.
[4:30] To do this, we go to the settings on the repository.
[4:32] Then we click on the branches menu option.
[4:34] We want to add a branch protection rule, so click on the add branch protection button.
[4:39] We fill in the branch name that we want to protect.
[4:41] Typically, this will be main, or if we’re dealing with an older repository, it could
[4:44] be master.
[4:45] I recommend enforcing pull requests for changes, and we want to turn on require status checks
[4:50] to pass before merging.
[4:52] This will prevent merging of a pull request unless all the actions have completed successfully.
[4:57] We just need to add our github action to the list of checks to pass.
[5:00] Now if someone creates a pull request, they will see the status checks, and if they push
[5:04] up broken code, then it will show the problem and they can fix their code.
[5:08] Once they have fixed it and pushed up the changes, then the status will change back
[5:11] to green.
[5:12] It’s magic.
[5:13] I have written a detailed blog post for this.
[5:15] The link is in the description, and I hope you’ll agree, you do need stinking badges.

HELP SUPPORT MY WORK: If you're feeling flush then please stop by Patreon Or you can make a one off donation via ko-fi
Want to keep up to date with the latest posts and videos? Subscribe to the newsletter
Blog Logo

Chris Greening

> Image


A collection of slightly mad projects, instructive/educational videos, and generally interesting stuff. Building projects around the Arduino and ESP32 platforms - we'll be exploring AI, Computer Vision, Audio, 3D Printing - it may get a bit eclectic...

View All Posts