mpy-ci

name	mpy-ci
description	Run the MicroPython CI pipeline locally using Docker. This skill should be used when working in a MicroPython repository and the user wants to run CI checks, build firmware, or test changes locally before pushing. Triggers on requests like "run CI", "test my changes", "build stm32", "run all checks", "run the linters", or any mention of local CI testing for MicroPython.

MicroPython Local CI

Run the full MicroPython CI pipeline locally in Docker, matching what GitHub Actions runs upstream.

Setup

The skill bundles two files that must be installed into the MicroPython repo:

1. ci/Dockerfile — Ubuntu 24.04 image with all toolchains (~15-20 GB)
2. ci/ci-local.sh — Runner script that invokes tools/ci.sh functions inside the container

Installation

To install the CI runner into a MicroPython repo:

1. Copy the bundled files into the repo:

   mkdir -p ci/
   cp <skill_path>/assets/Dockerfile ci/Dockerfile
   cp <skill_path>/scripts/ci-local.sh ci/ci-local.sh
   chmod +x ci/ci-local.sh
   

2. Add to .gitignore (build artifacts created by CI):

   esp-idf
   emsdk
   

3. Build the Docker image (takes 30-60 minutes on first run):

   ./ci/ci-local.sh --build
   

Prerequisites

• Docker installed and running
• For the unix-qemu target, register binfmt_misc handlers on the host:

  docker run --rm --privileged multiarch/qemu-user-static --reset
  echo -1 | sudo tee /proc/sys/fs/binfmt_misc/qemu-mipsn32 >/dev/null
  echo -1 | sudo tee /proc/sys/fs/binfmt_misc/qemu-mipsn32el >/dev/null
  

Available Targets

Port Builds and Tests

Target	Description	Runtime
stm32	STM32 firmware (pyboard, nucleo, misc boards)	~15 min
unix	Unix port: 15+ variant builds and full test suites	~45 min
unix-qemu	Cross-compiled unix (MIPS, ARM, RISC-V64) tested via qemu-user	~30 min
esp32	ESP32 variants (S2, S3, C3, C2, C5, C6, P4)	~20 min
esp8266	ESP8266 firmware and native modules	~2 min
rp2	RP2040/RP2350 boards	~10 min
qemu	Bare-metal QEMU (ARM Cortex-M/A, RISC-V rv32/rv64)	~60 min
cc3200	CC3200 (WiPy) firmware	~1 min
mimxrt	i.MX RT boards	~3 min
nrf	nRF boards	~3 min
powerpc	PowerPC firmware	~1 min
renesas	Renesas RA boards	~3 min
samd	SAMD boards	~3 min
alif	Alif Ensemble boards	~3 min
webassembly	WebAssembly/pyscript build and tests	~5 min
windows	MinGW cross-compile	~1 min
zephyr	Zephyr RTOS (runs on host, pulls own Docker image)	~30 min

Code Quality Checks

Target	Description
commit-format	Commit message formatting and sign-off (verifygitlog.py)
format	C code formatting (uncrustify)
codespell	Spell checking
ruff	Python linting and formatting
biome	JavaScript/TypeScript linting
docs	Sphinx documentation build
examples	Embedding examples build and test
mpy-format	.mpy file format tools and mpy-cross debug emitter
mpremote	mpremote wheel packaging

Meta Targets

Target	Description
all-checks	Run all code quality checks
all	Run all checks + all port builds

Usage

# Build the Docker image (first time or after Dockerfile changes)
./ci/ci-local.sh --build

# Run a single target
./ci/ci-local.sh unix

# Run multiple targets
./ci/ci-local.sh format codespell ruff stm32

# Run all code quality checks
./ci/ci-local.sh all-checks

# Build image and run targets in one command
./ci/ci-local.sh --build unix stm32

# Override the Docker image name
MICROPYTHON_CI_IMAGE=my-image:tag ./ci/ci-local.sh unix

Known Issues

• MPS2_AN385 (qemu target): The Cortex-M3 softfp board returns empty output for ~50% of tests when run in bulk via execpty: inside Docker. Individual tests pass. Other qemu boards (SABRELITE, MPS2_AN500, rv32, rv64) work correctly. Test runs are non-fatal (|| true).
• unix-qemu REPL tests: cmdline/repl_*.py and misc/sys_settrace_features.py fail under qemu-user-static emulation due to PTY handling differences. These are non-fatal.
• unix thread tests: thread/stress_schedule.py is flaky (sporadic timing-dependent failure). Not a ci-local.sh issue.
• Shared build state: Sequential variant builds in the unix target share build-* directories. The script inserts make clean calls between incompatible variants (32-bit/64-bit, cross-compiler changes) to prevent incremental build pollution.

Resources

scripts/ci-local.sh

The runner script. Handles Docker image building, container lifecycle, and target dispatch. Each target function calls one or more tools/ci.sh functions inside the container.

assets/Dockerfile

Ubuntu 24.04-based Docker image containing all toolchains: ARM GNU 14.3, ESP-IDF (version from repo lockfile), Emscripten SDK, RISC-V, MIPS, MinGW, PowerPC cross-compilers, QEMU, pico-sdk, and linting tools (uncrustify 0.72, codespell, ruff, biome, sphinx).