Run tests natively and build images directly from GitHub Actions using a chroot-based virtualized Raspberry Pi (raspios/raspbian) environment.
With this action, you can:
- run tests in an environment closer to a real embedded system, using qemu userland Linux emulation;
- build artifacts in such environment and upload them;
- prepare images that are ready to run on Raspberry Pi and other ARM embedded devices.
This action works with both 32 bits (arm) and 64 bits (aarch64) images.
Minimal usage is as follows:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: pguyot/arm-runner-action@v2
with:
commands: |
commands to run testsTypical usage to upload an image as an artifact:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: pguyot/arm-runner-action@v2
id: build_image
with:
base_image: raspios_lite:2022-04-04
commands: |
commands to build image
- name: Compress the release image
if: github.ref == 'refs/heads/releng' || startsWith(github.ref, 'refs/tags/')
run: |
mv ${{ steps.build_image.outputs.image }} my-release-image.img
xz -0 -T 0 -v my-release-image.img
- name: Upload release image
uses: actions/upload-artifact@v2
if: github.ref == 'refs/heads/releng' || startsWith(github.ref, 'refs/tags/')
with:
name: Release image
path: my-release-image.img.xzSeveral scenarios are actually implemented as tests.
The action has been tested with ubuntu-latest (currently equivalent to
ubuntu-20.04) and ubuntu-22.04. It requires a Linux kernel that is
compatible enough with the guest system as it uses qemu userland emulation. It
relies on binfmt.
The repository is copied to the image before the commands script is executed in the chroot environment. The commands script is copied to /tmp/ and is deleted on cleanup.
Commands to execute. Written to a script within the image. Required.
Base image to use. By default, uses latest raspios_lite image. Please note
that this is not necessarily well suited for continuous integration as
the latest image can change with new releases.
The following values are allowed:
raspbian_lite:2020-02-13raspbian_lite:latestraspios_lite:2021-03-04raspios_lite:2021-05-07raspios_lite:2021-10-30raspios_lite:2022-01-28raspios_lite:2022-04-04raspios_lite:2023-05-03raspios_lite:latest(armhf build, default)raspios_oldstable_lite:2023-05-03raspios_lite_arm64:2022-01-28(arm64)raspios_lite_arm64:2022-04-04(arm64)raspios_lite_arm64:2023-05-03(arm64)raspios_lite_arm64:latest(arm64)dietpi:rpi_armv6_bullseyedietpi:rpi_armv7_bullseyedietpi:rpi_armv8_bullseye(arm64)raspi_1_bullseye:20220121(armel)raspi_2_bullseye:20230102(armhf)raspi_3_bullseye:20230102(arm64)raspi_4_bullseye:20230102(arm64)raspi_1_bookworm:20230612(armel)raspi_2_bookworm:20230102(armhf)raspi_2_bookworm:20230612(armhf)raspi_3_bookworm:20230102(arm64)raspi_3_bookworm:20230612(arm64)raspi_4_bookworm:20230101(arm64)raspi_4_bookworm:20230612(arm64)
The input parameter also accepts any custom URL beginning in http(s)://...
It also accepts file:// URIs, which can be useful for caching steps in multistep builds. See cache test example.
More images will be added, eventually. Feel free to submit PRs.
Enlarge the image by this number of MB. Default is to not enlarge the image.
CPU to pass to qemu. Pass either a single CPU value or a pair
<arm_cpu>:<aarch64_cpu>.
Default is arm1176:cortex-a53, i.e. arm1176 for arm and cortex-a53 for
aarch64. This is the most compatible pair for Raspberry Pi. Indeed, arm1176
is the CPU of BCM2835 which is the SOC of first generation RaspberryPi and
RaspberryPi Zero, while cortex-a53 is the 64 bits CPU of the first 64 bits
Raspberry Pi models. Code compiled for arm1176 can be run on later 32 bits
CPUs.
The following values are specially processed:
arm1176equivalent toarm1176:cortex-a53.cortex-a7equivalent tocortex-a7:cortex-a53. Optimized for later Pi models (Pi 3/Pi 4 and Pi Zero 2). Not suitable for Pi 1/Pi 2/Pi Zero.cortex-a8equivalent tocortex-a8:max.cortex-a53equivalent tomax:cortex-a53.
Some software uses the output of uname -m or equivalent. This command is
directly driven by this cpu option. You might want to compile 32 bits
binaries with both arm1176 which translates to armv6l and cortex-a7 which
translates to armv7l.
For FPU and vector instruction sets, software usually automatically looks into
/proc/cpuinfo or equivalent. This can be patched with cpu_info option.
Whether code is executed in 32 bits or 64 bits (and build generates 32 bits or 64 bits binaries) depend on the image. See 32 and 64 bits below.
Source paths(s) inside the image to copy outside after the commands have
executed. Relative to the /<repository_name> directory or the directory
defined with copy_repository_path. Globs are allowed. To copy multiple paths,
provide a list of paths, separated by semicolons. Default is not to copy.
Destination path to copy outside the image after the commands have executed.
Relative to the working directory (outside the image). Defaults to .
Absolute path, inside the image, where the repository is copied or mounted.
Defaults to /<repository_name>. It is also the working directory where
commands are executed.
The repository is copied unless bind_mount_repository is set to true.
Bind mount the repository within the image instead of copying it. Default is to copy files.
If mounted, any modification of files within the repository by the target emulated system will persist after execution. It does not accelerate execution significantly but can simplify the logic by avoiding the copy artifact step from the target system.
Path to a fake cpu_info file to be used instead of /proc/cpuinfo. Default is
to not fake the CPU (/proc/cpuinfo will report amd64 CPU of GitHub runner).
Some software checks for features using /proc/cpuinfo and this option can be
used to trick them. The path is relative to the action (to use pre-defined
settings) or to the local repository.
Bundled with the action are the following 32 bits CPU infos:
cpuinfo/raspberrypi_zero_wcpuinfo/raspberrypi_3b(requirescortex-a7cpu)cpuinfo/raspberrypi_zero2_w(requirescortex-a7cpu)
As well as the following 64 bits CPU infos:
cpuinfo/raspberrypi_4bcpuinfo/raspberrypi_zero2_w_arm64
On real hardware, the /proc/cpuinfo file content depends on the CPU being
used in 32 bits or 64 bits mode, which in turn depends on the base image.
Consequently, you may want to use cpuinfo/raspberrypi_zero2_w_arm64 for
64 bits builds and cpuinfo/raspberrypi_zero2_w for 32 bits builds.
To avoid illegal instruction crashes, the cpu_info option must match what is
passed to cpu option. In particular, when using 32 bits cpu_info, the
default emulated CPU for 32 bits may not work and you should set cpu option
to cortex-a7.
Zero-fill unused filesystem blocks and shrink root filesystem during final clean-up, to make any later image compression more efficient. Default is to optimize image.
Use systemd-nspawn instead of chroot to run commands. Default is to use
chroot.
Additional options passed to systemd-nspawn. For example, -E CI=${CI} to pass
CI environment variable. See systemd-nspawn(1).
Index (starting with 1) of the root partition. Default is 2, which is suitable
for Raspberry Pi. NVIDIA Jetson images require 1. This is the partition that is
resized with image_additional_mb option.
Index (starting with 1) of the boot partition which gets mounted at /boot. Default is 1, which is suitable for Raspberry Pi. If the value is empty, the partition is not mounted.
Path to shell or shell name to run the commands in. Defaults to /bin/sh.
If missing, it will be installed. See shell_package.
If defined as basename filename, it will be used as long as the shell binary
exists under PATH after the package is installed.
Parameters can be passed to the shell, e.g.:
shell: /bin/bash -eo pipefailThe shell package to install, if different from shell. It may be handy with some shells that come packaged under a different package name.
For example, to use ksh93 as shell, set shell to ksh93 and
shell_package to ksh.
User to run commands within the image. It must exists.
By default, commands are run with user 0 (root).
Unless you are using systemd-nspawn, you can also specify the group with
the user:group syntax.
Exit immediately if a command exits with a non-zero status. Default is to exit.
Set to no or false to disable exiting on command failure. This only works
with sh, bash and ksh shells.
Copy artifacts if a command exits with a non-zero status. Default is to no copy.
Set to yes to copy artifacts.
Display executed commands as they are executed. Enabled by default.
Imports variables written so far to $GITHUB_ENV to the image. Default is not
to import any environment. This may be useful for sharing external variables with
the virtual environment. Set to yes or true to enable.
Practically, this setting allows constructs like ${VARIABLE_NAME} instead of
${{ env.VARIABLE_NAME }} within the command set.
Enables $GITHUB_ENV for commands in the image and exports its contents on
completion to subsequent tasks. This option is an alternative to using a
file-based artifact for passing the results of commands outside the image
environment.
Note this parameter does not enable importing any contents written to
$GITHUB_ENV ahead of running the commands. For that, use import_github_env.
Path to the image, useful after the step to upload the image as an artifact.
Many RaspberryPis and ARM boards are based on 64-bits chipsets than can run 32 bits and 64 bits kernels. RaspberryPi OS, as well as other distributions, are now provided in 32 bits and 64 bits flavors.
This action works for images built for 32 bits and 64 bits ARM architectures. Default input values imply 32 bits images. For 64 bits, the CPU and the base image should match.
The following matrix will build on armv6l, armv7l and aarch64 using the latest RaspberryPi OS images.
name: Test architecture matrix
on: [push, pull_request, workflow_dispatch]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
arch: [armv6l, armv7l, aarch64]
include:
- arch: armv6l
cpu: arm1176
base_image: raspios_lite:latest
cpu_info: raspberrypi_zero_w
- arch: armv7l
cpu: cortex-a7
base_image: raspios_lite:latest
cpu_info: raspberrypi_3b
- arch: aarch64
cpu: cortex-a53
base_image: raspios_lite_arm64:latest
cpu_info: raspberrypi_zero2_w_arm64_w
steps:
- uses: pguyot/arm-runner-action@v2
with:
base_image: ${{ matrix.base_image }}
cpu: ${{ matrix.cpu }}
cpu_info: ${{ matrix.cpu_info }}
commands: |
test `uname -m` = ${{ matrix.arch }}
grep Model /proc/cpuinfoInternally, the cpu value is embedded in a wrapper for qemu-arm-static and
qemu-aarch64-static. The actual qemu invoked depends on executables within
the base image.
Real world examples include:
- pguyot/wm8960 : compilation and tests
- nabaztag2018/pynab : compilation, tests and disk image.
Releases are listed on dedicated page. Release numbers follow semantic versionning : incompatible changes in invocation will be reflected with major release upgrades.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent