Preparing search index...

    Continuous Integration for Plugins

    Signal K provides a reusable GitHub Actions workflow that tests your plugin across all platforms where Signal K server runs. Even plugins without a test suite benefit — the workflow validates your plugin's structure, entry point, configuration schema, lifecycle, and API usage.

    Create .github/workflows/signalk-ci.yml in your plugin repository:

    name: SignalK Plugin CI

    on:
    push:
    branches: [main, master]
    pull_request:
    branches: [main, master]

    jobs:
    test:
    uses: SignalK/signalk-server/.github/workflows/plugin-ci.yml@master

    Push to GitHub — your plugin is now tested on Linux (x64 + arm64), macOS, and Windows.

    Add workflow_dispatch to get a "Run workflow" button in the GitHub Actions UI where you can override Node versions, enable integration tests, and more — without editing your workflow file.

    Because workflow_call and workflow_dispatch inputs are separate namespaces in GitHub Actions, the workflow needs two jobs: one for automatic runs (push/PR) with hardcoded defaults, and one for manual runs that passes through your form inputs.

    See examples/plugin-caller-example.yml for the full workflow with manual trigger support.

    Platform Architecture Notes
    Linux x64 GitHub-hosted runner
    Linux arm64 GitHub-hosted runner — Raspberry Pi 4/5
    macOS arm64 GitHub-hosted runner
    Windows x64 GitHub-hosted runner

    Each platform runs every Node version in the node-versions input; see the input table below for the default.

    There is no 32-bit ARM (armv7) platform: Signal K Server requires Node.js 22 or later and no longer supports armv7, as described in Breaking Changes.

    The plugin is built once, on Linux with Node build-node-version (24 by default), and every desktop and integration job tests that build output. After installing, the build job fails if dependencies, optionalDependencies or a non-optional peerDependencies entry is another App Store plugin or webapp (a package with the signalk-node-server-plugin, signalk-webapp or signalk-embeddable-webapp keyword); declare those in signalk.requires / signalk.recommends instead, see the requires and recommends section of Publishing. Desktop jobs install dependencies for their platform and Node version, then rebuild them so install scripts run and native addons are compiled, without rerunning the plugin's prepare script. Integration jobs do not rebuild the dependencies: they pack the build output and install it into the test server. The build command itself therefore runs only on that one platform and Node version. Set build-node-version if your build needs another Node.

    The desktop jobs (Linux, Linux arm64, macOS, Windows) run these checks, even if your plugin has no test suite. The list below is a summary for readers — the authoritative source for what the CI actually validates is the workflow itself: .github/workflows/plugin-ci.yml.

    package.json — signalk-node-server-plugin keyword, main or exports field, engines.node declaration

    Entry point — After build, verifies the plugin exports a constructor function

    plugin.schema() — Calls schema() and checks it returns a JSON-serializable schema-like object without crashing (not fully validated against the JSON Schema meta-schema)

    Lifecycle — Runs start() → stop() → start() (restart) with an empty configuration. Validates delta messages emitted during startup and checks that registerDeltaInputHandler handlers forward deltas correctly.

    Async crashes — Watches for roughly 1.5 seconds after the lifecycle calls return and fails the job if the plugin fails asynchronously in that window — an unhandled 'error' event (which ends the server process) or a floating promise that rejects late. A failure that takes longer to surface will not be caught, so a clean run is not proof there is none. See Crashing the server after start() below.

    API usage — Scans source files for:

    • Deprecated APIs (setProviderStatus → setPluginStatus, setProviderError → setPluginError)
    • Internal server properties (app.server, app.deltaCache, app.pluginsMap)
    • Route registration anti-patterns (direct app.get() instead of registerWithRouter())
    • File storage anti-patterns (writing to __dirname or process.cwd() instead of app.getDataDirPath())
    • Security anti-patterns (accessing app.securityStrategy or isDummy() — plugin routes are already protected by the server)
    • Node built-in module version mismatches (node:sqlite requires engines.node >= 22.5.0)

    npm pack — Verifies all files referenced by main/exports are included in the published package

    App Store compatibility — Installs the plugin with --ignore-scripts (as the App Store does) and checks for native addon dependencies

    Stray files — Warns when build and test steps leave untracked files

    Override defaults by passing inputs to the shared workflow:

    jobs:
    test:
    uses: SignalK/signalk-server/.github/workflows/plugin-ci.yml@master
    with:
    test-command: 'npm run test:ci'
    build-command: 'npm run build:plugin'
    enable-signalk-integration: true
    node-versions: '["24"]'
    Input Default Description
    test-command npm test Command to run your test suite
    build-command npm run build --if-present Build command
    format-check-command (empty) Blocking format check (e.g. npm run prettier:check, npx biome check .); skipped when empty
    coverage-command (empty) Runs tests with coverage (e.g. npm run coverage); replaces the standard test run and writes output to the step summary
    node-versions see below Node versions for the desktop and integration jobs
    build-node-version 24 Node version that runs the build once, on Linux
    artifact-name-suffix (empty) Suffix for the artifact names; set it only when one workflow run calls plugin-ci more than once
    enable-armv7 false Deprecated and ignored — there is no armv7 platform
    enable-signalk-integration false Start SignalK server for integration tests
    signalk-server-versions ["latest"] JSON array of signalk-server versions; the integration job fans out over each

    The node-versions default is every Node.js version Signal K Server supports; the workflow input holds the current list, and its validation rejects versions the server does not support.

    Both are tool-agnostic command strings — the workflow doesn't care whether you use Prettier/Biome or c8/nyc/jest --coverage. Leave either empty to opt out.

    with:
    format-check-command: 'npm run prettier:check'
    coverage-command: 'npm run coverage'

    format-check-command runs after lint and blocks the job if it fails (unlike npm run lint --if-present, which is advisory). coverage-command replaces the standard Run tests step — its stdout is captured and appended to the GitHub Actions step summary so you can see coverage output without digging through logs.

    The CI validates the same fields described in the publishing guide. The most important for CI:

    • keywords must include signalk-node-server-plugin
    • main or exports must point to your entry file
    • engines.node should declare the minimum Node.js version (required if you use node:sqlite or other version-specific built-in modules)

    Plugins without a test script still get all validation checks — tests are skipped with a notice.

    Enable enable-signalk-integration: true to run your plugin against a real Signal K server.

    The job installs a Signal K server, packs and installs your plugin, auto-enables it, and starts the server with sample NMEA 0183 + NMEA 2000 data so the plugin has a realistic data environment (navigation, wind, depth, temperature, battery, and more). It then verifies the plugin loaded, checks provider API registrations, and runs npm run test:integration if defined. Your tests receive SIGNALK_URL=http://localhost:3000 to connect to the running server.

    The authoritative sequence of steps lives in the workflow itself: .github/workflows/plugin-ci.yml.

    Pass signalk-server-versions as a JSON array to fan the integration job out over multiple server versions — useful for catching regressions across the baconjs 1 → 3 transition (server 2.23.x vs 2.24.0+) and similar cross-generation breakage:

    with:
    enable-signalk-integration: true
    signalk-server-versions: '["2.23.0", "latest"]'

    The integration job runs the full Cartesian product of node-versions × signalk-server-versions, so its job count is the product of the two list lengths (see the node-versions input above for its default). To keep the matrix small, shrink either dimension. node-versions also sets the desktop matrix, so a shorter list (for example node-versions: '["24"]') cuts the desktop jobs as well.

    If your plugin registers as a provider for one of the server's provider APIs, the integration test verifies the registration actually works by calling the corresponding endpoint:

    Provider API Registration method Endpoint checked
    History API v2 app.registerHistoryApiProvider() /signalk/v2/api/history/values must not return 501

    This catches a common class of bugs where a plugin calls a registration method but the endpoint still returns "no provider configured" — for example due to an API mismatch between the plugin and the server version being tested.

    For testing against actual hardware (GPIO, CAN bus, serial ports), add a self-hosted runner on a Cerbo GX or Raspberry Pi:

    test-cerbo-hardware:
    name: Cerbo GX (real hardware)
    runs-on: [self-hosted, cerbo-gx]
    steps:
    - uses: actions/checkout@v6
    - run: npm ci
    - run: npm test

    The server does not sandbox plugins. Everything runs in one Node process, so an error your plugin fails to handle does not disable just that plugin — it terminates the whole server. Under a process supervisor (Restart=always, Docker's restart: unless-stopped) the server then restart-loops: it comes up, runs for a few seconds, dies again, and keeps going indefinitely.

    The dangerous case is the one that escapes try/catch. Wrapping the body of start() is not enough, because two common failures arrive after start() has already returned successfully:

    Unhandled 'error' events. In Node, 'error' is special: an EventEmitter that emits it with no listener attached throws, and there is nothing up the stack to catch it. Sockets, streams, D-Bus connections, serial ports and MQTT clients all report failures this way.

    Attach an 'error' listener to every emitter your plugin holds, at the point you create it, and report the failure through app.setPluginError(). A listener that only handles the success event ('data', 'message', 'connect') leaves the failure path unguarded.

    A library opening the connection for you does not remove the obligation — if it hands back an emitter and attaches no listener itself, the responsibility is still yours.

    Floating promises. An async call started but never awaited (and with no .catch()) becomes an unhandled rejection. Node terminates the process for these by default, but the server installs an unhandledRejection handler: it logs the rejection and, when the originating plugin can be identified from the stack, records a plugin error. So a floating rejection usually degrades your plugin rather than killing the server — the failure is silent from the user's point of view, and the work you meant to do never happened.

    Either await the call inside start(), so its own error handling applies, or — when the work must continue in the background — attach a rejection handler when you kick it off. What fails the check is a call whose rejection nothing observes.

    The general rule: a plugin should report failures through app.setPluginError() and keep the process alive. Hardware that is absent, a socket that is missing, a remote service that is down — these are normal conditions on a boat, not reasons to take navigation data offline.

    CI installs uncaughtException and unhandledRejection handlers around the lifecycle check and fails the job if either fires, including when start(), stop() and restart all report success.

    The check is an error rather than a warning because of the first case. The server's own uncaughtException handler logs the error and flags the plugin, but it cannot stop an unhandled 'error' event: Node throws on those synchronously, and the throw ends the process regardless of what the handler logged. One faulty emitter therefore takes the whole server down, and the resulting crash-loop is difficult for users to trace back to its cause.