PlatformIO CI/CD

This guide covers CI/CD for firmware projects that use PlatformIO — projects with a platformio.ini at the repository root (or in a known subdirectory checked out by your workflow). The firmngin/ota action auto-detects PlatformIO when platformio.ini is present and platform is auto (default).

When to use PlatformIO CI/CD

Scenario	PlatformIO CI/CD fit
Multi-environment builds (`esp32dev`, `esp8266`, custom envs)	Excellent — use `platformio-env` per target
PlatformIO library dependencies	Supported — `lib_deps` resolved during `pio run`
Monorepo with firmware in a subfolder	Supported — run workflow with `working-directory`
Arduino sketch without `platformio.ini`	Use Arduino CLI CI/CD instead

Project requirements

Your repository should include:

File / setting	Purpose
`platformio.ini`	PlatformIO project definition
`[env:...]` section	At least one build environment
Valid `board` and `platform`	Produces a flashable `.bin`
Matching firmngin board/model	Device or template board fields align with your PlatformIO target

Example minimal platformio.ini:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
lib_deps =
  firmngin/Firmngin-Arduino

How auto-detection works

When platform: auto (default):

The action checks for platformio.ini in the repository root.
If found, PlatformIO is selected.
If platformio-env is empty, the action resolves the environment in this order:
- default_envs from platformio.ini
- First [env:name] block in the file
Runs pio run --environment <env>.
Uploads the compiled firmware to firmngin.

Always set platformio-env explicitly in production workflows to avoid surprises when you add new environments to platformio.ini.

Basic workflow

name: PlatformIO OTA

on:
  push:
    branches:
      - main

permissions:
  contents: read

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

      - uses: firmngin/ota@v1.1.3
        with:
          token: ${{ secrets.FIRMNGIN_API_TOKEN }}
          device-template-id: ${{ vars.FIRMNGIN_DEVICE_TEMPLATE_ID }}
          platform: platformio
          platformio-env: esp32dev
          version: ${{ github.run_number }}

Firmware in a subdirectory

If platformio.ini is not at the repo root:

jobs:
  ota:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: firmware
    steps:
      - uses: actions/checkout@v4

      - uses: firmngin/ota@v1.1.3
        with:
          token: ${{ secrets.FIRMNGIN_API_TOKEN }}
          device-template-id: ${{ vars.FIRMNGIN_DEVICE_TEMPLATE_ID }}
          platform: platformio
          platformio-env: esp32dev

The action runs from the job working directory, so platformio.ini must be inside firmware/.

Multiple environments

Option A: Matrix jobs (recommended)

Upload one artifact per hardware target:

jobs:
  ota:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - platformio-env: esp32dev
            target-board: esp32
            target-model: esp32
            template-var: FIRMNGIN_ESP32_TEMPLATE_ID
          - platformio-env: esp8266
            target-board: esp8266
            target-model: esp8266
            template-var: FIRMNGIN_ESP8266_TEMPLATE_ID
    steps:
      - uses: actions/checkout@v4

      - uses: firmngin/ota@v1.1.3
        with:
          token: ${{ secrets.FIRMNGIN_API_TOKEN }}
          device-template-id: ${{ vars[matrix.template-var] }}
          platform: platformio
          platformio-env: ${{ matrix.platformio-env }}
          version: ${{ github.sha }}

Define one template variable per fleet in GitHub Variables.

Option B: Single environment per workflow file

Maintain separate workflow files per product line, each with a fixed platformio-env.

Board and model alignment

firmngin uses board name and board model to match firmware artifacts to devices. Your PlatformIO board setting must correspond to the values configured on:

The device template (fleet OTA), or
The device (single-device OTA), or
The target-board / target-model inputs (artifact-only upload).

PlatformIO `board` (example)	Typical firmngin `target-board`	Typical firmngin `target-model`
`esp32dev`	`esp32`	`esp32`
`esp8266`	`esp8266`	`esp8266`

If upload fails with a target mismatch error, compare your template or device board fields with the values sent by CI/CD.

Optimizing binary size

CI/CD uploads are limited to 10 MB. Common PlatformIO optimizations:

build_flags =
  -Os
  -DCORE_DEBUG_LEVEL=0
board_build.partitions = default.csv

Additional tips:

Disable verbose logging in release builds.
Remove unused libraries from lib_deps.
Use partition schemes appropriate for your flash size.

Build flags per environment

Use environment-specific sections for release vs debug:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
build_type = release
build_flags =
  -DFIRMNGIN_RELEASE=1

[env:esp32dev_debug]
extends = env:esp32dev
build_type = debug
build_flags =
  -DCORE_DEBUG_LEVEL=5

Point CI/CD at the release environment only:

platformio-env: esp32dev

Caching PlatformIO dependencies (optional)

Speed up builds by caching PlatformIO packages:

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

      - name: Cache PlatformIO
        uses: actions/cache@v4
        with:
          path: |
            ~/.platformio
          key: platformio-${{ runner.os }}-${{ hashFiles('**/platformio.ini') }}

      - uses: firmngin/ota@v1.1.3
        with:
          token: ${{ secrets.FIRMNGIN_API_TOKEN }}
          device-template-id: ${{ vars.FIRMNGIN_DEVICE_TEMPLATE_ID }}
          platform: platformio
          platformio-env: esp32dev

The firmngin/ota action installs PlatformIO on each run; caching reduces download time for platforms and libraries.

Local verification before CI/CD

Run a local PlatformIO build with the same environment before pushing:

pip install platformio
pio run --environment esp32dev

Fix compile errors locally first — CI will fail on the same issues.

PlatformIO + single device

For one device without a template:

- uses: firmngin/ota@v1.1.3
  with:
    token: ${{ secrets.FIRMNGIN_API_TOKEN }}
    device-secret-id: ${{ secrets.FIRMNGIN_DEVICE_SECRET_ID }}
    platform: platformio
    platformio-env: esp32dev

Ensure the device has board name and model set in the dashboard to match your PlatformIO target.

Common issues

Issue	Fix
Environment not detected	Set `platformio-env` explicitly
Build fails in CI	Confirm `pio run` succeeds locally for the same environment
Board/model mismatch	Align device or template board fields with your PlatformIO target
Works locally, fails in CI	Confirm all source files are committed; check workflow `working-directory`

Getting started

Core concepts

Monetization

Libraries

When to use PlatformIO CI/CD

Project requirements

How auto-detection works

Basic workflow

Firmware in a subdirectory

Multiple environments

Option A: Matrix jobs (recommended)

Option B: Single environment per workflow file

Board and model alignment

Optimizing binary size

Build flags per environment

Caching PlatformIO dependencies (optional)

Local verification before CI/CD

PlatformIO + single device

Common issues

​When to use PlatformIO CI/CD

​Project requirements

​How auto-detection works

​Basic workflow

​Firmware in a subdirectory

​Multiple environments

​Option A: Matrix jobs (recommended)

​Option B: Single environment per workflow file

​Board and model alignment

​Optimizing binary size

​Build flags per environment

​Caching PlatformIO dependencies (optional)

​Local verification before CI/CD

​PlatformIO + single device

​Common issues

​Related

When to use PlatformIO CI/CD

Project requirements

How auto-detection works

Basic workflow

Firmware in a subdirectory

Multiple environments

Option A: Matrix jobs (recommended)

Option B: Single environment per workflow file

Board and model alignment

Optimizing binary size

Build flags per environment

Caching PlatformIO dependencies (optional)

Local verification before CI/CD

PlatformIO + single device

Common issues

Related