CI/CD overview

CI/CD lets you build firmware in GitHub and publish it to firmngin automatically. Each successful run can upload a new artifact and, depending on how you configure the workflow, start an OTA rollout to your fleet or a single device. This path is separate from manual uploads in Dashboard → Firmware → Artifacts. CI/CD uses a scoped API token so your pipeline can publish firmware without sharing your dashboard login.

Setup overview

Complete these steps in order before your first CI/CD run:

Step	Action
1	Generate an API token in the dashboard
2	Add the token to GitHub Secrets
3	Add GitHub Secrets and variables (token, device ID, `keys.h` if needed)
4	Add the workflow file to your firmware repository

You must generate and save the API token before configuring GitHub Actions. The token is shown only once at creation time.

Step 1: Generate an API token

Every CI/CD pipeline needs a workspace API token with the Firmware OTA scope. Generate it from the dashboard first — do not skip this step.

Open Integrations

Log in to firmngin.dev.
Select the workspace that owns your devices or device templates.
In the sidebar, open Integrations (below Billing).

The Integrations page lists existing API tokens for the workspace. If you have no tokens yet, the empty state shows a Generate Token button.

Create the token

Click Generate Token (top right, or from the empty state).
On the Generate API Token page, fill in:
- Token name — a label you will recognize later (for example github-ota-production or staging-firmware).
- Scopes — check Firmware OTA. At least one scope is required.
Click Generate Token.

Copy the token immediately

After generation, firmngin shows the full token once. A warning banner reminds you that it will not be shown again.

Click Copy next to the token value.
Paste it into a password manager or directly into GitHub Secrets (see Step 2).
Click OK to return to the Integrations list.

If you close the page without copying the token, you cannot recover it. Revoke the token and generate a new one.

Token format

Copy the entire token exactly as shown on the Generate Token screen.

Manage tokens later

From Integrations, you can:

Action	How
View active tokens	See name, scopes, created date, and last used date
Revoke a token	Click Revoke on the token row — revoked tokens stop working immediately
Create another token	Click Generate Token — use separate tokens per environment (production vs staging)

Scope tokens to Firmware OTA only. Do not grant broader permissions than your pipeline needs.

Step 2: Add the token to GitHub

After copying the token from Step 1, store it as a GitHub secret (never as a variable or in workflow YAML).

Open your firmware repository on GitHub.
Go to Settings → Secrets and variables → Actions.
Click New repository secret.
Set:
- Name: FIRMNGIN_API_TOKEN
- Secret: paste the full token from Step 1
Click Add secret.

Reference it in workflows as ${{ secrets.FIRMNGIN_API_TOKEN }}.

Step 3: Add GitHub Secrets and variables

Go to Settings → Secrets and variables → Actions.

Secrets (required)

Name	When to set	Value
`FIRMNGIN_API_TOKEN`	Always	Full token from Step 1
`FIRMNGIN_DEVICE_SECRET_ID`	Single-device OTA	Device Secret ID from the dashboard
`FIRMNGIN_KEYS_H`	Arduino sketches using `#include <firmngin.h>`	Full contents of your local `keys.h` file

Never commit keys.h to git. Add it to .gitignore and inject it in CI from the FIRMNGIN_KEYS_H secret.

Example workflow step for Arduino projects:

- name: Prepare keys.h
  env:
    KEYS_H: ${{ secrets.FIRMNGIN_KEYS_H }}
  run: printf '%s\n' "$KEYS_H" > MySketch/keys.h

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

Variables (optional)

Non-secret identifiers can live in Variables:

Name	When to set
`FIRMNGIN_DEVICE_TEMPLATE_ID`	Fleet OTA via device template

You can also store FIRMNGIN_DEVICE_SECRET_ID as a secret (recommended) instead of a variable. See Where to find IDs below.

What CI/CD covers

Step	Handled by
Checkout source code	Your GitHub workflow
Build firmware binary	PlatformIO or Arduino CLI
Upload artifact to firmngin	`firmngin/ota` GitHub Action
Start OTA (optional)	firmngin, based on workflow inputs

Deployment modes

Choose one target mode per workflow run:

Mode	Input	What happens after upload
Fleet OTA	`device-template-id`	firmngin matches board/model from the template and starts rollout according to the template Firmware OTA policy. Monitor progress under Firmware → Workflow runs.
Single device	`device-secret-id`	firmngin uploads the artifact and immediately triggers OTA on that one device. Best when you have one device without a template.
Artifact only	`target-board` + `target-model`	firmngin stores the firmware only. Deploy manually from Firmware → Artifacts when you are ready.

Do not combine device-template-id and device-secret-id in the same workflow run. They are mutually exclusive.

Prerequisites

Before adding CI/CD to a repository:

A firmngin workspace with at least one registered device or device template.
Firmware source that builds with PlatformIO (platformio.ini) or Arduino CLI (sketch folder with matching .ino filename).
Board and model on your device or template must match the compiled firmware target.
For fleet rollouts, a Firmware OTA policy attached to the target device template (see OTA policy).
For single-device deploy, the device must have board name and board model set in the dashboard.

High-level architecture

Configure GitHub repository

This section expands Step 2 and Step 3 above. In your firmware repository, go to Settings → Secrets and variables → Actions.

Secrets

Name	Value
`FIRMNGIN_API_TOKEN`	Full token copied in Step 1
`FIRMNGIN_DEVICE_SECRET_ID`	Device Secret ID (single-device OTA)
`FIRMNGIN_KEYS_H`	Full `keys.h` content (Arduino + Firmngin library)

Variables

Name	Used when
`FIRMNGIN_DEVICE_TEMPLATE_ID`	Fleet OTA via device template

Where to find IDs

Device template ID

Open Dashboard → Device templates.
Open the template you use for fleet devices.
Copy the template UUID from the URL or template detail panel.

Device secret ID

Open Dashboard → Devices.
Select your device.
Copy the Secret ID shown on the device page.

Step 4: Minimal workflow

Fleet OTA (device template)

name: Firmngin 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 }}

Single device (Arduino + Firmngin library)

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

Sketch layout for the example above:

path_to_your_folder/
  path_to_your_file.ino
  keys.h          ← generated in CI, gitignored locally

For a sketch at the repo root instead, use arduino-sketch: path_to_your_file.ino and write keys.h to the repository root. See Arduino CLI CI/CD for both layouts. See GitHub Actions for complete workflow examples, all inputs, versioning, and troubleshooting.

Build tool guides

Guide	When to use
PlatformIO	Projects with `platformio.ini`, multiple environments, or PlatformIO libraries
Arduino CLI	Arduino sketch folders with `.ino` files and FQBN-based builds

Upload limits and versioning

Constraint	Value
Maximum firmware file size	10 MB
Version label	Set via workflow input, or auto-generated from git tag / commit
Supported binary	`.bin` from PlatformIO or Arduino CLI

The action resolves version in this order:

version input, if you set it.
git describe --tags --always --dirty, if git history is available.
First 12 characters of the commit SHA.

Use explicit versioning for production releases (for example 1.2.0 or 2026.07.16).

After a successful run

Deployment mode	What to check
Fleet (template)	Firmware → Workflow runs — approval, waves, fleet progress, device logs
Single device	Firmware → Workflow runs or the device OTA status in Devices
Artifact only	Firmware → Artifacts — deploy manually when ready

Security practices

Never commit API tokens, keys.h, or device secret keys to git.
Scope tokens to Firmware OTA only.
Revoke unused tokens from Integrations.
Use branch protection and required reviews on main before OTA runs.
Prefer canary or staged_expand policies for production fleets (see Fleet rollout).

Getting started

Core concepts

Monetization

Libraries

Setup overview

Step 1: Generate an API token

Open Integrations

Create the token

Copy the token immediately

Token format

Manage tokens later

Step 2: Add the token to GitHub

Step 3: Add GitHub Secrets and variables

Secrets (required)

Variables (optional)

What CI/CD covers

Deployment modes

Prerequisites

High-level architecture

Configure GitHub repository

Secrets

Variables

Where to find IDs

Step 4: Minimal workflow

Fleet OTA (device template)

Single device (Arduino + Firmngin library)

Build tool guides

Upload limits and versioning

After a successful run

Security practices

​Setup overview

​Step 1: Generate an API token

​Open Integrations

​Create the token

​Copy the token immediately

​Token format

​Manage tokens later

​Step 2: Add the token to GitHub

​Step 3: Add GitHub Secrets and variables

​Secrets (required)

​Variables (optional)

​What CI/CD covers

​Deployment modes

​Prerequisites

​High-level architecture

​Configure GitHub repository

​Secrets

​Variables

​Where to find IDs

​Step 4: Minimal workflow

​Fleet OTA (device template)

​Single device (Arduino + Firmngin library)

​Build tool guides

​Upload limits and versioning

​After a successful run

​Security practices

​Related

Setup overview

Step 1: Generate an API token

Open Integrations

Create the token

Copy the token immediately

Token format

Manage tokens later

Step 2: Add the token to GitHub

Step 3: Add GitHub Secrets and variables

Secrets (required)

Variables (optional)

What CI/CD covers

Deployment modes

Prerequisites

High-level architecture

Configure GitHub repository

Secrets

Variables

Where to find IDs

Step 4: Minimal workflow

Fleet OTA (device template)

Single device (Arduino + Firmngin library)

Build tool guides

Upload limits and versioning

After a successful run

Security practices

Related