I use GitHub Actions workflows to run automated builds, tests, and checks on my repositories.
I develop and test my workflows before pushing them to GitHub with the act
tool created by GitHub user nektos.
This section documents some conventions I use with my actions, along with examples of workflows that I use across my repos. See GitHub's comprehensive documentation for more details on action terminology and workflow syntax.
GitHub Actions have a feature called reusable workflows which essentially allows one workflow to call another workflow. This makes it convenient to have a "base" workflow (referred to as a "called workflow") in a central location that does most of the work, and a per-repository workflow (referred to as a "caller workflow") which configures the settings needed to run the base workflow.
Taking advantage of reusable workflows becomes especially useful when you need to make a change to the functionality of an action that is used in multiple repos (like when I had to fix the issue with act
as described below). Instead of having to make the change in every repo which uses the action, all that needs to change is the single base workflow. See .github/workflows for the reusable workflows that my repos call.
I have a workflow_dispatch
trigger (including an optional input string) on all my workflows so that I can trigger them manually from the repo Actions screen:
workflow_dispatch:
inputs:
message:
description: Message to display in job summary
required: false
type: string
For any workflow that can trigger multiple job runs based on different combinations of varibles, I use a matrix strategy. Even if the repo only needs to be compiled for one platform, I still use a matrix strategy for consistency with my other repos and my reusable workflows.
For compiling arduino sketches across multiple platforms:
compile-sketches:
strategy:
matrix:
include:
- arch: avr
fqbn: 'arduino:avr:uno'
platform-name: 'arduino:avr'
platform-sourceurl: 'https://downloads.arduino.cc/packages/package_index.json'
- arch: msp-G2
fqbn: 'energia:msp430:MSP-EXP430G2553LP'
platform-name: 'energia:msp430'
platform-sourceurl: 'https://raw.githubusercontent.com/Andy4495/TI_Platform_Cores_For_Arduino/main/json/package_energia_minimal_MSP_107_index.json'
- arch: msp-F5529
fqbn: 'energia:msp430:MSP-EXP430F5529LP'
platform-name: 'energia:msp430'
platform-sourceurl: 'https://raw.githubusercontent.com/Andy4495/TI_Platform_Cores_For_Arduino/main/json/package_energia_minimal_MSP_107_index.json'
- arch: msp432
fqbn: 'energia:msp432r:MSP-EXP432P401R'
platform-name: 'energia:msp432r'
platform-sourceurl: 'https://raw.githubusercontent.com/Andy4495/TI_Platform_Cores_For_Arduino/main/json/package_energia_minimal_MSP432r_index.json'
- arch: tivac
fqbn: 'energia:tivac:EK-TM4C123GXL'
platform-name: 'energia:tivac'
platform-sourceurl: 'https://raw.githubusercontent.com/Andy4495/TI_Platform_Cores_For_Arduino/main/json/package_energia_minimal_TM4C_104_alternate_index.json'
- arch: esp8266
fqbn: 'esp8266:esp8266:thing'
platform-name: 'esp8266:esp8266'
platform-sourceurl: 'http://arduino.esp8266.com/stable/package_esp8266com_index.json'
For triggering builds on multiple repos which are dependent on a library:
build-dependent-repos:
strategy:
matrix:
include:
- name: Trigger build on <Repo Name>
repo: <Repo name>
I have several template workflows available in my .github repository:
-
- Arduino
compile-sketches
workflow with matrix build definitions for various hardware platforms. - Update the matrix list as needed for the repo being compiled.
- Arduino
-
- Checks for dead links in Markdown files. Automatically runs once a month.
- Note that you also need to create a file named
mlc_config.json
.
-
-
Used with libraries published to the Arduino library manager to confirm that they meet the Arduino Library Spec rules.
-
This workflow as written does not work with
act
because it requires theGITHUB_TOKEN
secret whichact
does not supply by default. This could be fixed with a little extra code and some local setup, but I don't find this necessary because the arduino-lint tool can be easily run directly from the command line:arduino-lint --verbose --compliance strict --library-manager update
-
-
- Used to validate "clean" markdown code.
- Note that you also need to create a file named
markdownlintconfig.json
- I typically do not run this as an action, but instead use the related VSCode extension to check my Markdown code.
-
- Automatically trigger a compile-sketches action on repos that depend on a library that I updated.
- This also uses a matrix strategy to define the list of repos that are triggered.
act
uses Docker with customized images to create a local environment similar to the environment used by GitHub Actions. The default act
image is intentionally incomplete to keep its size manageable. While it works well for many actions, there are issues that arise since the environments are not quite the same.
Release v1.1.0 of the compile-sketches
action changed the Python and related tools configuration to make the action incompatible with the default act
image (catthehacker/ubuntu:act-latest
).
In particular, the following messages will be appear in the act
output when trying to use compile-sketches
v1.1.0 and the ubuntu:act-latest
image, and the job will fail:
| installing poetry from spec 'poetry==1.4.0'...
| ⚠️ File exists at
| /root/.local/bin/poetry and points
| to /root/.local/venv/bin/poetry,
| not /root/.local/pipx/venvs/poetry
| /bin/poetry. Not modifying.
| installed package poetry 1.4.0, installed using Python 3.11.2
| - poetry (symlink missing or pointing to unexpected location)
| done! ✨ 🌟 ✨
To fix this problems, /root/.local/bin
needs to be added to the shell's PATH so that the poetry
executable can be found:
steps: # Existing code
- uses: actions/checkout@main # Existing code
# *** Add the code below ***
- name: Update PATH if using nektos/act locally
if: ${{ env.ACT }}
run: |
echo "/root/.local/bin" >> $GITHUB_PATH
By checking for the environment variable env.ACT
first, the PATH update step is only run when using act
.
Note that versions of the ubuntu:act-latest
image published before 18-Sep-2023 have additional issues, but the latest published version only requires the above change (see 61 and 74).
If you see the following error when running the compile-sketches
job:
::error::rm: cannot remove '/opt/hostedtoolcache/Python/3.11.2': Directory not empty
Then try running the following command:
rm -r ~/.cache/act/actions-setup-python@v5
I am pretty sure that I have only noticed this problem on newly installed setups. I do not completely understand what causes the problem, but deleting the local cache and forcing act
to re-download setup-python
(instead of using a local copy) fixes it.
When using act
, I occasionally run into timeout and rate-limiting errors that aren't specific to the actions themselves. These errors can generally be cleared by waiting a few minutes and then re-running the action.
Examples of the errors:
Downloading index: package_index.tar.bz2 Get "https://downloads.arduino.cc/packages/package_index.tar.bz2": dial tcp: lookup downloads.arduino.cc on 192.168.1.1:53: read udp 192.168.1.1:33527->192.168.1.1:53: i/o timeout
arduino:avr-gcc@7.3.0-atmel3.6.1-arduino7 read tcp 192.168.1.1:57018->104.18.1.1:80: read: connection reset by peer
Error during install: read tcp 192.168.1.1:57018->104.18.1.1:80: read: connection reset by peer
Error: Error response from daemon: Head "https://ghcr.io/v2/catthehacker/ubuntu/manifests/act-latest": Get "https://ghcr.io/token?scope=repository%3Acatthehacker%2Fubuntu%3Apull&service=ghcr.io": context deadline exceeded
::error::API rate limit exceeded for 73.1.1.1. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)
- ::error::API rate limit exceeded
The GitHub Actions extension for VSCode does not recognize the env.ACT
variable and flags an issue in the Problems window when you open an action YAML file for editing:
Context access might be invalid: ACT
This is documented in several issues (67, 61, 47) and there does not appear to be a plan to fix it. Some issue comments claim that it is fixed, but it is not.
While the basic issue is slightly annoying, a more annoying aspect is that the message does not go away when you close the editor window. This causes the Problems window to become cluttered with the messages. The only way to clear the messages after closing the file editor is to disable/enable the extension or quit and restart VSCode.
The act
tool caches external repos (i.e., GitHub repos that aren't the current repo under test). This can create issues when debugging reusable workflows. If you push a change to a reusable workflow stored in another repo, act
will use a cached version of the workflow without the updates. This can make it appear that a fix didn't work even though it should have.
I work around this by deleting the cache directory any time I update the reusable workflows. The default cache location is ~/.cache/act
. My reusable workflows are stored in my .github
repo on the main
branch, so I run the following to delete the cache:
rm -rf ~/.cache/act/Andy4495-.github@main
This may be related to one of these issues: 1785, 1912, 1913. I haven't researched this any further, and there may be other solutions than just deleting the cache directory.
When running act
under Windows WSL, you may see an error similar to the following:
Could not get auth config from docker config: error getting credentials - err: exec: "docker-credential-desktop.exe": executable file not found in $PATH, out: ''
This can be fixed by updating the file (within WSL) ~/.docker/config.json
and changing credsStore
to credStore
. You may need to restart Docker for this change to take effect.
This issue has been fixed with the release of act
version 0.2.54. More details can be found here.
act
tool- GitHub Actions
- Docker
- Docker images for
act
compile-sketches
action- markdown-link-check action
- arduino-lint action
- arduino-lint command-line tool
- markdownlint action
- Markdownlint extension for VSCode
- GitHub Actions extension for VSCode
The software and other files in this repository are released under what is commonly called the MIT License. See the file LICENSE.txt
in this repository.