Run on OnMCU

A composite GitHub Action that flashes and runs firmware on real MCU hardware via OnMCU, and fails the workflow if the hardware run fails.

It installs the OnMCU CLI, writes a CI config, and invokes onmcu run in a single step. Because it is a composite action rather than a Docker action, there is no image to pull and startup overhead is minimal.

Quick start

- uses: actions/checkout@v4

- uses: onmcu/onmcu-action@v1
  with:
    board: NUCLEO-H743ZI
    file: target/thumbv7em-none-eabihf/release/my-firmware
    api-key: ${{ secrets.ONMCU_API_KEY }}

Required inputs are board, file, and api-key. Everything else has a sensible default.

Inputs

Input	Required	Default	Description
board	yes	—	Target board identifier, e.g. NUCLEO-H743ZI.
file	yes	—	Firmware to flash and run (ELF, BIN, or HEX), relative to working-directory.
api-key	yes	—	OnMCU API key. Pass a secret.
server	no	https://ctrl1.onmcu.com	OnMCU control-plane URL.
version	no	latest	OnMCU CLI version to install (e.g. 0.0.1) or latest.
chunk-size	no	5	Upload chunk size for firmware transfer.
retries	no	3	Transport retries.
timeout	no	600	Per-run timeout in seconds.
working-directory	no	.	Directory to run in; file resolves against it.
args	no	""	Extra raw arguments appended to onmcu run.

Tip: Pin version to a specific release (e.g. 0.4.1) for reproducible CI.
Relying on latest means the CLI can change between workflow runs without a action.yml change. |

Exit code

The action surfaces the hardware run's outcome: the workflow succeeds only when the OnMCU job completes successfully, and fails with a non-zero exit code on a failed, cancelled, or timed-out run. For reproducible CI behavior, pin version instead of relying on latest.

Full example — build a Rust crate, then run it

Mirrors the typical embedded flow: build with Cargo, capture the ELF path, then run it on the matching board.

name: Hardware
on: [push]

permissions:
  contents: read

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Provision Rust toolchain and targets
        run: rustup show

      - uses: Swatinem/rust-cache@v2

      - name: Build
        id: build
        working-directory: nucleo-h743zi
        run: |
          elf=$(cargo build --release --message-format=json \
            | jq -r 'select(.reason=="compiler-artifact" and .executable!=null) | .executable' \
            | tail -n1)
          echo "elf=$elf" >> "$GITHUB_OUTPUT"

      - uses: onmcu/onmcu-action@v1
        with:
          board: NUCLEO-H743ZI
          file: ${{ steps.build.outputs.elf }}
          api-key: ${{ secrets.ONMCU_API_KEY }}

Maintainer release process

For maintainers, tag releases as vMAJOR.MINOR.PATCH and move a floating v1 tag to the latest compatible release. This lets consumers pin @v1 and receive non-breaking updates:

git tag -a v1.0.0 -m "v1.0.0"
git tag -fa v1 -m "Update v1 tag"
git push --tags --force

License

See LICENSE.