Native-addon CI prebuilds

holepunchto/actions is a collection of reusable composite GitHub Actions. This page covers the ones for authors of native Bare addons who build prebuilt binaries across platforms in CI. Reference one with:

- uses: holepunchto/actions/<name>@v1

Prebuild pipeline

The typical shape is a build matrix where each job runs compile-prebuilds, then a final job merges the per-platform artifacts.

compile-prebuilds inputs

platform and arch are optional. compile-prebuilds passes --platform and --arch to bare-make generate only when they are set, and bare-make builds for the host without them. Set both when upload is true, because upload-prebuilds requires them and names the artifact from them. flags is passed on to bare-make generate, and path is the directory that holds the source tree to compile.

wasi and musl default to false. Set wasi: true to install the WASI sysroot for targeting WASI, and musl: true to install the musl sysroot for targeting musl. compile-prebuilds passes both inputs to setup-bare-make, and they do nothing else. The target itself is still chosen with platform, arch, and flags; see the bare-make toolchain notes for the wasi-wasm32 and musl targets.

WebAssembly prebuilds

From Bare 1.36.0, an addon package can ship a WebAssembly build next to its native ones, which Bare loads sandboxed through WASI when an import asks for it with the host attribute, or when there is no native build for the platform. See WebAssembly addons. The build is one more matrix entry, with wasi set so that setup-bare-make installs wasi-sysroot. This is how bare-sqlite 0.1.5 builds its prebuilds:

strategy:
  matrix:
    include:
      # ...the native platforms
      - os: ubuntu-24.04
        platform: wasi
        arch: wasm32
steps:
  - uses: holepunchto/actions/bare-base@v1
  - uses: holepunchto/actions/compile-prebuilds@v1
    with:
      platform: ${{ matrix.platform }}
      arch: ${{ matrix.arch }}
      wasi: ${{ matrix.platform == 'wasi' }}
      upload: true

What the job builds:

The imports of the result are checked when it loads, not when it builds. Bare loads it through bare-wasm-abi, which rejects an addon that imports a libjs function it does not implement, such as threadsafe functions or the event loop. Load the built addon under Bare with require('.', { with: { host: 'wasi-wasm32' } }) from the package directory to check it.

Project and toolchain setup

These are the supporting actions for a prebuild job. Use any of them directly in a workflow.

See also

• Native addons—writing the addon this pipeline builds.
• bare-make reference—the build tool compile-prebuilds runs.
• Bare modules—the runtime the prebuild pipeline targets.
• Holepunch GitHub Actions—the same holepunchto/actions collection's Pear app CI/CD and release actions.