name: Run on Architecture
on:
push:
branches:
- main
jobs:
run_on_arch:
runs-on: ubuntu-22.04
name: Build on ARM Architecture
steps:
- uses: actions/checkout@v4
- uses: uraimo/run-on-arch-action@v2
name: Run commands on ARM
with:
arch: armv7
distro: ubuntu22.04
githubToken: ${{ github.token }}
run: |
uname -a
echo ::set-output name=uname::$(uname -a)
Run on Architecture
A GitHub Action that executes commands on non-x86 CPU architectures via QEMU.
What is Run on Architecture GitHub Action?â
This GitHub Action allows you to execute commands on non-x86 CPU architectures such as ARM, AARCH64, S390X, and PPC64LE by leveraging QEMU. It enables you to build and test projects on architectures that are not natively supported by GitHub-hosted runners.
How to Run Commands on Non-x86 Architecturesâ
Use the arch
, distro
, and run
inputs to define the architecture, Linux distribution, and the commands to run in the container.
with:
arch: armv7
distro: ubuntu22.04
run: |
uname -a
How to Use a Matrix for Architecture Combinationsâ
You can use a matrix to build on multiple architecture and distribution combinations:
strategy:
matrix:
include:
- arch: aarch64
distro: ubuntu22.04
- arch: ppc64le
distro: alpine_latest
steps:
- uses: uraimo/run-on-arch-action@v2
with:
arch: ${{ matrix.arch }}
distro: ${{ matrix.distro }}
How to Cache Docker Images with GitHub Tokenâ
To speed up builds, you can cache Docker images using your GitHub token by passing githubToken
:
with:
githubToken: ${{ github.token }}
How to Customize the Container Environmentâ
You can pass environment variables, customize the shell, and add Docker run arguments:
with:
env: |
VAR_NAME=value
shell: /bin/bash
dockerRunArgs: |
--volume "${PWD}/artifacts:/artifacts"
How to Use a Custom Base Imageâ
If you need to use a custom base image, set the base_image
parameter:
with:
base_image: riscv64/busybox
arch: none
distro: none
Supported Architectures and Distributionsâ
Here are some valid combinations of architecture and Linux distributions:
Architecture | Supported Distros |
---|---|
armv6 | stretch, buster, bullseye, alpine_latest |
armv7 | ubuntu20.04, ubuntu22.04, alpine_latest |
aarch64 | ubuntu22.04, fedora_latest, alpine_latest |
ppc64le | alpine_latest, ubuntu22.04 |
s390x | ubuntu22.04, bullseye, alpine_latest |
Invalid combinations will result in a failure.
QEMU Emulation for Architecturesâ
This action uses QEMU to emulate different architectures. Due to the nature of software emulation, you should expect slower performance compared to running on native x86 architectures.