OpenHPS reusable workflows

Shared GitHub Actions workflows for every repository in the OpenHPS organisation. They replace 24 independently hand-forked main.yml files, which had drifted to the point where only three of them shared a single line of history.

Callers pin the moving @v1 tag. A breaking change to any workflow gets a v2 tag, so a CI change can never break 28 repositories at once.

Third-party actions used inside this repository are pinned to full commit SHAs with a trailing # vN comment. This repository is a supply-chain chokepoint for every OpenHPS package, which is the one place where tag mutability genuinely matters.

module.yml

CI for a standard @openhps/* package: build, lint, test, docs, coverage reporting, GitHub Pages deployment, and npm release.

Inputs

Input	Type	Default	Purpose
node-versions	string (JSON array)	'["22","24"]'	Versions to build and test against
release-node	string	'22'	Version used for lint, docs, release and artifact upload
prebuild-script	string	''	npm script that generates sources before build/lint/docs
run-size-limit	boolean	false	Run npm run size after the build
run-typedoc	boolean	true	Build the TypeDoc API documentation
graphviz	boolean	false	Install Graphviz (required by typedoc-umlclass)
services-compose	string	''	Docker compose file bringing up test service containers
publish-docs	boolean	true	Deploy docs to GitHub Pages from master
publish-npm	boolean	true	Publish to npm from master (latest) and dev (dev)

Secrets

Both are optional; pass them with secrets: inherit.

Secret	Used by
NPM_TOKEN	the release job
CODECOV_TOKEN	the report job (Codecov v5 needs it for reliable uploads)

Job graph

build (matrix) ──┬─> test (matrix) ──> report
                 └─> docs ──┐
lint ───────────────────────┼─> publish-docs
                            │
build, lint, test ──────────┴─> release

lint deliberately does not depend on build: it runs prebuild-script itself, so lint feedback arrives in about a minute instead of after a full build.

Design rules

Each of these fixes a concrete failure mode in the workflows this replaces.

1. Every job runs checkout → setup-node (cache: npm) → npm ci. Previously only the build job installed anything; quality, test_coverage and documentation relied on an actions/cache hit for **/node_modules and used the runner's default Node. On a cache miss they either failed confusingly or, worse, ran a lint step that silently matched nothing.
2. node_modules and dist are never cached. Build output moves between jobs as artifacts with if-no-files-found: error, so a missing artifact fails loudly. setup-node caches only ~/.npm, which is content-addressed and keyed on the lockfile, so a miss costs time and never correctness. (The old dist cache key used github.run_number, which can never hit on the job that writes it.)
3. npm ci, never npm install. Thirteen repositories ran npm install and fourteen ran bare yarn install, both of which silently rewrite the lockfile in CI.
4. lint runs prebuild-script. The old quality job ran type-aware ESLint rules while generated sources (src/three in core) were absent from the tree.

monorepo.yml

CI for the private npm-workspace roots (openhps-capacitor, openhps-cordova, openhps-web). Installs once at the root and drives --workspaces --if-present for build, test and publish.

Inputs: node-versions, release-node, publish-npm. Secret: NPM_TOKEN.

auto-merge.yml

Dependabot auto-merge. Uses dependabot/fetch-metadata plus gh pr merge --auto --squash, and only auto-merges patch and minor updates to devDependencies, so any runtime dependency bump still gets a human look.

This replaces a configuration that combined permissions: write-all with a blanket target: minor auto-merge through a third-party action.

paper.yml

JOSS paper build for openhps-core only.

Note the path filter is docs/paper/**, not ./docs/paper/**. GitHub path patterns are repository-root-relative and reject a leading ./, so the previous filter never matched and the push/PR triggers had never once fired.

Caller examples

Standard module

.github/workflows/ci.yml:

name: CI

on:
    push:
        branches: [master, dev]
    pull_request:
        branches: [master, dev]
    workflow_dispatch:

concurrency:
    group: ${{ github.workflow }}-${{ github.ref }}
    cancel-in-progress: ${{ github.ref != 'refs/heads/master' }}

jobs:
    ci:
        uses: OpenHPS/workflows/.github/workflows/module.yml@v1
        secrets: inherit
        with: {}

concurrency must be set in the caller — a reusable workflow cannot declare it.

openhps-core

Core vendors three.js into src/three before anything can compile, budgets its web bundles, and renders UML class diagrams that need Graphviz on PATH:

jobs:
    ci:
        uses: OpenHPS/workflows/.github/workflows/module.yml@v1
        secrets: inherit
        with:
            prebuild-script: 'build:three'
            run-size-limit: true
            graphviz: true

A module needing service containers

jobs:
    ci:
        uses: OpenHPS/workflows/.github/workflows/module.yml@v1
        secrets: inherit
        with:
            services-compose: 'test/docker-compose.ci.yml'

Monorepo root

jobs:
    ci:
        uses: OpenHPS/workflows/.github/workflows/monorepo.yml@v1
        secrets: inherit
        with: {}

Requirements a caller must satisfy

• package-lock.json committed, and a packageManager field pinning npm.
• Scripts: build, lint, cover:ci, and build:typedoc (unless run-typedoc: false).
• cover:ci must write a non-empty test-results.xml and coverage/cobertura-coverage.xml. The canonical test/.mocharc.ci.json + test/.mocha-multi-reporters.json pair does this; note that putting reporterEnabled at the top level of .mocharc.json does not, which is why the fleet published zero test results for years while CI consumed the file.
• bump:release and bump:development scripts (commit-and-tag-version) for the release job.