đŸ”ĨSave up to $132K/month in CI costs!Try Free→
Skip to main content
← Back to workflows

How to Run Commands on Non-x86 Architectures with GitHub Action

uraimo-run-on-arch-action -
GitHub Action
2.7.2
682
Contributors
Contributor - uraimoContributor - elijahrContributor - leoniloris
Categories
Usage
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-arch-action logo

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:

ArchitectureSupported Distros
armv6stretch, buster, bullseye, alpine_latest
armv7ubuntu20.04, ubuntu22.04, alpine_latest
aarch64ubuntu22.04, fedora_latest, alpine_latest
ppc64lealpine_latest, ubuntu22.04
s390xubuntu22.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.