Arduino CLI CI/CD

Use this guide for Arduino-style projects — sketch folders with a matching .ino file and a board identifier (FQBN). The firmngin/ota GitHub Action handles build and upload when platformio.ini is not present.

When to use Arduino CLI CI/CD

Scenario	Fit
Sketch folder or root `.ino` layout	Excellent
Sketches with Firmngin library (`#include <firmngin.h>`)	Supported
PlatformIO project	Use PlatformIO CI/CD
Multiple sketches in one repo	Set `arduino-sketch` explicitly

Sketch path in your repo

Set arduino-sketch to the sketch path relative to the repository root. You can include or omit the .ino extension — the action accepts both.

arduino-sketch: path_to_your_file.ino

The path must match where the .ino file actually lives in your repo after checkout.

Layout A — sketch in a subfolder (Arduino IDE default)

Use a folder whose name matches the .ino filename (Arduino convention):

path_to_your_folder/
  path_to_your_file.ino    ← filename must match folder name
  keys.h

arduino-sketch: path_to_your_folder/path_to_your_file.ino
# or shorthand when folder and file share the same name:
arduino-sketch: path_to_your_folder

Place keys.h in the same folder as the .ino file:

run: printf '%s\n' "$KEYS_H" > path_to_your_folder/keys.h

Layout B — sketch at repo root

A single .ino at the repository root is also valid:

path_to_your_file.ino
keys.h

arduino-sketch: path_to_your_file.ino

run: printf '%s\n' "$KEYS_H" > keys.h

A lone .ino at the root is fine when you set arduino-sketch explicitly. If you omit arduino-sketch and rely on auto-detect, the action picks the first .ino it finds — use an explicit path when the repo has more than one sketch.

Complete workflow example (single device)

name: Firmngin OTA

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read

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

      - name: Prepare keys.h
        env:
          KEYS_H: ${{ secrets.FIRMNGIN_KEYS_H }}
        run: |
          if [ -z "$KEYS_H" ]; then
            echo "Missing secret FIRMNGIN_KEYS_H" >&2
            exit 1
          fi
          printf '%s\n' "$KEYS_H" > path_to_your_folder/keys.h

      - uses: firmngin/ota@v1.1.3
        with:
          token: ${{ secrets.FIRMNGIN_API_TOKEN }}
          device-secret-id: ${{ secrets.FIRMNGIN_DEVICE_SECRET_ID }}
          platform: arduino
          arduino-fqbn: esp32:esp32:esp32
          arduino-sketch: path_to_your_folder/path_to_your_file.ino
          version: ci-${{ github.run_number }}

GitHub Secrets

Secret	Value
`FIRMNGIN_API_TOKEN`	Token from Integrations (Firmware OTA)
`FIRMNGIN_KEYS_H`	Full contents of local `keys.h`
`FIRMNGIN_DEVICE_SECRET_ID`	Device Secret ID from the dashboard

Add keys.h to .gitignore — never commit it.

What the action handles

For Arduino builds, firmngin/ota prepares dependencies, compiles your sketch, uploads firmware, and triggers OTA when configured. No separate library install step is required in your workflow.

Board identifier (FQBN)

Find the correct value in Arduino IDE or Arduino CLI board list. Common ESP targets:

Hardware	Example FQBN
ESP32 Dev Module	`esp32:esp32:esp32`
ESP8266 NodeMCU	`esp8266:esp8266:nodemcuv2`

Fleet OTA via template

- uses: firmngin/ota@v1.1.3
  with:
    token: ${{ secrets.FIRMNGIN_API_TOKEN }}
    device-template-id: ${{ vars.FIRMNGIN_DEVICE_TEMPLATE_ID }}
    platform: arduino
    arduino-fqbn: esp32:esp32:esp32
    arduino-sketch: path_to_your_folder/path_to_your_file.ino

Inject keys.h in a prior step when using the Firmngin library.

Local verification

Build locally with the same board target before pushing. Install the Firmngin Arduino library and place keys.h beside your sketch.

Common issues

Issue	Fix
Sketch not found	Match `arduino-sketch` to your repo path (for example `path_to_your_folder/path_to_your_file.ino` or root `path_to_your_file.ino`)
Upload target missing	Add `FIRMNGIN_DEVICE_SECRET_ID` to GitHub Secrets
Build fails in CI	Upgrade to latest `firmngin/ota` tag; verify sketch layout
Missing `keys.h`	Add `FIRMNGIN_KEYS_H` secret + Prepare step in workflow
Library missing locally	Follow Arduino library installation

Security

Never commit keys.h.
Store credentials only in GitHub Secrets.
Remove hardcoded WiFi passwords from sketches before pushing to public repos.

Getting started

Core concepts

Monetization

Libraries

When to use Arduino CLI CI/CD

Sketch path in your repo

Layout A — sketch in a subfolder (Arduino IDE default)

Layout B — sketch at repo root

Complete workflow example (single device)

GitHub Secrets

What the action handles

Board identifier (FQBN)

Fleet OTA via template

Local verification

Common issues

Security

​When to use Arduino CLI CI/CD

​Sketch path in your repo

​Layout A — sketch in a subfolder (Arduino IDE default)

​Layout B — sketch at repo root

​Complete workflow example (single device)

​GitHub Secrets

​What the action handles

​Board identifier (FQBN)

​Fleet OTA via template

​Local verification

​Common issues

​Security

​Related

When to use Arduino CLI CI/CD

Sketch path in your repo

Layout A — sketch in a subfolder (Arduino IDE default)

Layout B — sketch at repo root

Complete workflow example (single device)

GitHub Secrets

What the action handles

Board identifier (FQBN)

Fleet OTA via template

Local verification

Common issues

Security

Related