pear-ci GitHub Action

The pear-ci GitHub Action stages a directory from your repository into a Hyperdrive on every run, producing a stable pear:// link your app can use as its upgrade field. For the task-oriented setup, see Publish with GitHub Actions.

It is a composite action that installs the pear-ci npm tool, fetches the committed snapshot from main, stages, and commits the updated snapshot back. Every run except a dry run of an empty drive needs a peer that holds the drive, as Peers and timeouts describes.

Each run installs the latest pear-ci from npm, whichever version of the action you pin: @v1 pins the action's steps, not the tool. Where this page names pear-ci 0.1.2, it describes that release.

UsageCopy Anchor Link

- uses: holepunchto/actions/pear-ci@v1
  with:
    primary-key: ${{ secrets.PEAR_PRIMARY_KEY }}
    namespace: my-app
    target: dist
    dry-run: false

InputsCopy Anchor Link

OutputsCopy Anchor Link

Input validationCopy Anchor Link

The action rejects malformed inputs before staging:

• primary-key must match ^[a-fA-F0-9]{64}$.
• namespace must match ^[a-zA-Z0-9._-]+$.
• target must contain only [a-zA-Z0-9_./-], must not be an absolute path, and must not contain .. (no directory traversal).
• dry-run must be exactly true or false.

Snapshot commitsCopy Anchor Link

The action reads ci/snapshot.json from a branch named main before staging and writes it back to main afterward. The action hard-codes the branch name. The snapshot records each core's length so subsequent runs sync only what changed. When dry-run is true, no commit is made.

The file must exist before the first run. Commit it to main containing an empty list, []. Without it, the Fetch snapshot from main step fails with gh: Not Found (HTTP 404).

Grant the workflow contents: write (and pull-requests: write if you want the PR fallback) so the snapshot commit can land.

The action commits the snapshot on top of the commit the run checked out. If pushing it directly to main fails, the action pushes a pear-ci/snapshot-<run-id> branch and opens a PR, exposing its URL via the pr-url output. The push fails when someone pushed to main during the run, and on every run if branch protection blocks direct pushes to main. Until you merge that PR, main holds an older snapshot than the drive, so every run fails before it stages with Core <key> length (<n>) is higher than length in snapshot.json. Merge it before the next run.

With the default github-token, the PR fallback also needs Allow GitHub Actions to create and approve pull requests turned on in the repository's Actions settings. Without it, the step fails after it pushes the branch, and you have to open the PR yourself.

Peers and timeoutsCopy Anchor Link

A runner starts with no copy of the drive, so each run relies on a peer that holds it, such as an always-on machine running pear seed on the drive's link. pear-ci waits on that peer twice, with no time limit:

• Before staging, until a peer reports each core at its length in the snapshot. It logs syncing <key> to length <n> for each core, dry runs included. If a peer reports a core longer than the snapshot records, the run fails with Core <key> length (<n>) is higher than length in snapshot.json. That happens while a snapshot PR from an earlier run isn't merged yet (see Snapshot commits), and after a run stopped partway through its upload (see the warning below).
• After staging, until a peer holds every block of the drive, the new release included. It logs waiting synced remote peers for key <drive-key>, then all remote peers synced.

With no peer online, a run waits at one of these lines until a peer connects or the job's timeout-minutes ends it, which defaults to 360 minutes. Starting a seeder while the run waits lets it finish. Set timeout-minutes on the job, well over the time your largest release takes to reach the seeder.

Underlying CLICopy Anchor Link

Outside of Actions, the same staging runs through the pear-ci CLI:

npm install -g pear-ci
pear-ci \
  --primary-key <64-hex-key> \
  --name my-app \
  --target ./dist \
  --snapshot ci/snapshot.json \
  --storage /tmp/store

The CLI logs the drive key it stages to (starting stage for key <drive-key>)—that key is your pear:// link. With --output, it also writes the key and length to a file, so a script does not have to parse the log. The action uses it to set its length output. See the pear-ci README for the programmatic API and snapshot format.

See alsoCopy Anchor Link

• Publish with GitHub Actions—step-by-step setup.
• Holepunch GitHub Actions—the full catalog of shared actions this is part of.
• Configuration—the upgrade field this link feeds.
• Hyperdrive and Hyperswarm—the building blocks pear-ci stages and replicates over.
• Deploy your application—the manual staging flow.