Holepunch GitHub Actions

Reference for the shared composite GitHub Actions in holepunchto/actions used to build, sign, publish, and recover Pear applications.

holepunchto/actions is a collection of reusable composite GitHub Actions for building, signing, publishing, and recovering Pear applications and Holepunch modules. Reference one with:

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

There is no project-scaffolding action. To bootstrap a new Pear project, clone the hello-pear-electron template. The actions below automate CI/CD once a project exists.

Pear app CI/CD

Action	Purpose	Key inputs / outputs
`make-pear-app`	Run an npm script (`make` by default) for the host OS with code signing and notarization, then upload the files you name as workflow artifacts. Doesn't set up Node.js or install dependencies; precede it with `actions/checkout@v4`, `node-base-extended`, and `run-npm-script`. See Build and sign desktop apps in CI.	In: `channel` (required) plus the macOS, Mac App Store, Windows, and Linux groups in `make-pear-app` inputs. Out: none
`pear-ci`	Stage a directory into a Hyperdrive on every run, producing a stable `pear://` link. Documented in full at pear-ci GitHub Action.	`primary-key`, `namespace`, `target`, `dry-run`; out: `pr-url`
`pear-provision-recover`	Recover a provision drive from the network into a new writable drive (runs the `pear-provision-recover` CLI). Used to rebuild write access—see Recovering from lost write access.	`path`, `key`, `length`, `blobs-length`, `primary-key`, `name` (all required)

Every input is optional except channel. The action doesn't check that the inputs for a signing method are all set, so pass the full set for each method you use. action.yml is the source of truth, and make-pear-app has no outputs.

Each file input names a file under out/make that your npm script writes; the action matches out/make/**/<name> and fails the job when nothing matches. It uploads the file as a workflow artifact named after the file, unless you set the matching *_artifact_name input.

Build

Input	Notes
`channel`	Required. Exported to the build as `CHANNEL`.
`upgrade_key`	Exported as `UPGRADE_KEY` when set. The template's `forge.config.js` writes it to `package.json#upgrade`.
`script`	The npm script to run. Default `make`.
`host`	Exported as `HOST`.
`sfw`	Run the script through Socket Firewall. Default `true`, which needs `sfw` on the `PATH`; `node-base-extended` installs it.
`standalone`, `standalone_artifact_name`	A standalone executable to upload, and its artifact name.

macOS

Input	Notes
`macos_dmg`, `macos_dmg_artifact_name`	A `.dmg` to upload, and its artifact name.
`macos_app`	The file name for a ZIP of the `.app` bundle, which the action creates with `ditto` and uploads under that name.
`macos_development_certificate_base64`, `macos_development_password`	The Developer ID Application certificate as a base64-encoded `.p12`, and its password.
`macos_codesign_identity`	Exported as `MAC_CODESIGN_IDENTITY`. When it's empty, the template's `forge.config.js` doesn't sign.
`macos_notarization_method`	`appstore_connect` or `apple_id_password`. When set, the action stores notarytool credentials in a keychain profile named `notary` and exports it as `KEYCHAIN_PROFILE`.
`macos_api_key_base64`, `macos_api_key_id`, `macos_api_issuer`	For `appstore_connect`: the base64-encoded App Store Connect API key (`AuthKey_<id>.p8`), its 10-character key ID, and the issuer UUID.
`macos_apple_id`, `macos_apple_password`, `macos_apple_team_id`	For `apple_id_password`: the Apple ID email, an app-specific password, and the Apple Developer Team ID.

Mac App Store

Set script to make:mas for this build.

Input	Notes
`macos_mas_pkg`, `macos_mas_pkg_artifact_name`	The `.pkg` to upload, and its artifact name.
`macos_distribution_certificate_base64`, `macos_distribution_password`	The Apple Distribution certificate as a base64-encoded `.p12`, and its password.
`macos_distribution_identity`	Exported as `MAS_DISTRIBUTION_IDENTITY`.
`macos_installer_distribution_certificate_base64`, `macos_installer_distribution_password`	The installer distribution certificate as a base64-encoded `.p12`, and its password.
`macos_installer_distribution_identity`	Exported as `MAS_INSTALLER_DISTRIBUTION_IDENTITY`.
`macos_distribution_provisioning_profile_base64`	A base64-encoded provisioning profile. The action copies the decoded file to `~/Library/MobileDevice/Provisioning Profiles/app.mas.provisionprofile` and exports its path as `MAS_PROVISIONING_PROFILE`.

Windows

Input	Notes
`windows_signing_method`	`cert_sha1` or `cert_pfx`. The action's conditions compare these exact strings; the upstream README writes `windows_cert_sha1` and `windows_cert_pfx`, and `windows_cert_pfx` skips the `.pfx` import.
`windows_cert_sha1`	For `cert_sha1`: the SHA-1 thumbprint of a certificate on the runner.
`windows_cert_pfx_base64`, `windows_cert_password`	For `cert_pfx`: the base64-encoded `.pfx`, and its password. The action imports it and uses its thumbprint.
`windows_msix`, `windows_msix_artifact_name`	An `.msix` to upload, and its artifact name.
`windows_zip`, `windows_zip_artifact_name`	A `.zip` to upload, and its artifact name.

The action exports the thumbprint as WINDOWS_CERT_SHA1 and points WINDOWS_SIGN_HOOK at its bundled windows-sign.js.

Linux

Input	Notes
`linux_appimage`, `linux_appimage_artifact_name`	An AppImage to upload, and its artifact name.
`linux_snap`, `linux_snap_artifact_name`	A Snap to upload, and its artifact name. Setting `linux_snap` also installs Snapcraft and LXD on the runner.
`linux_flatpak`, `linux_flatpak_artifact_name`	A Flatpak archive to upload, and its artifact name.

Release

Action	Purpose	Key inputs
`publish`	`npm publish` (honoring dist-tag and workspaces) then create a GitHub release via `create-release`.	`tag` (default `latest`), `workspaces`, `include-workspace-root`, `node-auth-token`
`create-release`	`npm pack` the packages and attach the tarballs to a `gh release create` for the current ref.	`workspaces`, `include-workspace-root`
`trigger-canary`	Dispatch a `release` event to the `holepunchto/canary-tests` repo so downstream canary tests run against a new release.	`repository`, `ref`, `token` (all required)