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