GitHub Actions

​

Action reference

- uses: firmngin/ota@v1.1.3
  with:
    token: ${{ secrets.FIRMNGIN_API_TOKEN }}
    device-template-id: ${{ vars.FIRMNGIN_DEVICE_TEMPLATE_ID }}
    device-secret-id: ${{ secrets.FIRMNGIN_DEVICE_SECRET_ID }}
    target-board: esp32
    target-model: esp32
    platform: auto
    platformio-env: esp32dev
    arduino-fqbn: esp32:esp32:esp32
    arduino-sketch: path_to_your_file.ino
    version: 1.0.0
    release-notes: "Bug fixes and performance improvements"

​

Inputs

​

What happens on each run

1. Detect PlatformIO or Arduino project.
2. Install the build toolchain for your board.
3. Compile firmware.
4. Resolve a version label.
5. Upload to firmngin and start OTA when a target is configured.

​

Workflow examples

​

Fleet OTA on push to main

name: Production OTA

on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  ota:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: firmngin/ota@v1.1.3
        with:
          token: ${{ secrets.FIRMNGIN_API_TOKEN }}
          device-template-id: ${{ vars.FIRMNGIN_DEVICE_TEMPLATE_ID }}
          version: ${{ github.ref_name }}
          release-notes: ${{ github.event.head_commit.message }}

​

Single device (no template)

name: Single device OTA

on:
  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: 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

​

Artifact only (manual deploy later)

- uses: firmngin/ota@v1.1.3
  with:
    token: ${{ secrets.FIRMNGIN_API_TOKEN }}
    target-board: esp32
    target-model: esp32
    version: ${{ github.ref_name }}

​

Pull request build (no upload)

​

Matrix build (multiple boards)

​

Version pinning

- uses: firmngin/ota@v1.1.3

​

After a successful run

• Dashboard → Firmware → Artifacts — new firmware version
• Dashboard → Firmware → Workflow runs — OTA progress (fleet or single device)

​

Troubleshooting

​

Token missing or invalid

• Store FIRMNGIN_API_TOKEN as a GitHub secret.
• Regenerate the token in Integrations with Firmware OTA scope if auth fails.

​

No deploy target configured

• Set exactly one mode: device-template-id, device-secret-id, or both target-board and target-model.
• For single-device mode, store FIRMNGIN_DEVICE_SECRET_ID in Secrets — an empty value causes this failure.

​

Arduino sketch not found

• Set arduino-sketch to the path of your .ino file relative to the repo root.
• Subfolder layout: path_to_your_folder/path_to_your_file.ino (folder name usually matches the .ino filename).
• Root layout: path_to_your_file.ino at the repository root.
• Put keys.h in the same directory as the sketch file.

​

Build succeeded but upload step failed

• Upgrade to the latest firmngin/ota release tag.
• Confirm secrets and workflow inputs are set.

​

Library download message in logs

• Normal during Arduino builds — the action prepares dependencies before compile.

​

Template or device mismatch

• Confirm board/model on the device or template matches your build target.
• For fleet OTA, verify the template has an active Firmware OTA policy.

​

Device does not update after upload

• Confirm the device is online.
• Check Firmware → Workflow runs and device logs in the dashboard.

​

Firmware file too large

• Maximum size is 10 MB. Optimize build flags or reduce bundled assets.

​

Related

• CI/CD overview
• PlatformIO
• Arduino CLI
• OTA policy
• Workflow control