Publish with GitHub Actions

The simplest way to publish and update a Pear app is to let CI do it. The pear-ci GitHub Action stages a directory from your repository into a Hyperdrive on every push, so shipping a new version is just a git push. There is no local pear touch or pear stage to run by hand. You do need one peer that stays online: every run syncs the drive from a peer before it stages, and waits for a peer to download the new release after, so keep pear seed running on an always-on machine.

This is the goal-oriented recipe. If you need the full-control flow—release lines, provision, and multisig—use Deploy your application instead. The two are not mutually exclusive: CI is the fast path for development and staging links, while the manual flow gives you production gating.

How it worksCopy Anchor Link

The action wraps the pear-ci tool. On each run it:

1. Installs pear-ci and fetches the committed ci/snapshot.json from the main branch.
2. Joins Hyperswarm and syncs the drive from a connected peer up to the lengths recorded in the snapshot.
3. Mirrors your target directory into a Hyperdrive whose key is derived deterministically from primary-key + namespace, then waits until a connected peer has downloaded every new block.
4. Commits the updated ci/snapshot.json back to main (or opens a PR if the push is rejected).

Three properties shape how this works in CI:

• The pear:// link is stable. Because the drive key comes from the secret primary key plus the namespace, every run stages to the same link. You set that link once as your app's upgrade field and every push updates it.
• The snapshot replaces persistent storage. ci/snapshot.json records each core's length, so the next run only syncs what changed instead of re-uploading the whole drive or persisting a full Corestore between jobs.
• A peer has to hold the drive. A fresh runner has no copy of the drive, so it depends on a peer twice: before staging, to sync up to the lengths the snapshot records, and after staging, to take the new release. Neither wait has a time limit, so a run with no peer online waits until the job times out. An always-on seeder fills that role.

Before you beginCopy Anchor Link

You need:

1. A GitHub repository for your app, with a branch named main.
2. The directory you want to publish committed to that repo—typically the pear build deployment directory, your app source if you stage the runnable project directly, or a mobile OTA payload's dist/ (see Build the OTA payload).
3. A 32-byte hex primary key (created below) stored as a repository secret.
4. A namespace name (any string of letters, numbers, dots, hyphens, or underscores) that identifies this drive.
5. An always-on machine with Pear installed, to seed the drive (see Keep a seeder online).

Generate and store the primary keyCopy Anchor Link

Generate a random 32-byte key:

openssl rand -hex 32
# 9f2c... (64 hex characters)

Add it to your repository as a secret named PEAR_PRIMARY_KEY (Settings → Secrets and variables → Actions → New repository secret).

Commit an empty snapshotCopy Anchor Link

The action reads ci/snapshot.json from a branch named main before it stages, and commits the updated file back to main after. The action hard-codes the branch name. Before the first run, commit the file with an empty list:

mkdir -p ci
echo '[]' > ci/snapshot.json
git add ci/snapshot.json
git commit -m "Add the pear-ci snapshot"
git push origin main

Without this file, the action's Fetch snapshot from main step fails with gh: Not Found (HTTP 404).

Add the workflowCopy Anchor Link

Create .github/workflows/pear-ci.yml:

name: Publish with pear-ci

on:
  push:
    branches: [main]

# pear-ci commits the updated snapshot back to main
permissions:
  contents: write
  pull-requests: write

concurrency:
  group: pear-ci
  cancel-in-progress: false

jobs:
  stage:
    runs-on: ubuntu-latest
    # Ends a run that waits for a peer. Keep it well above your largest upload.
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v4
      - uses: holepunchto/actions/pear-ci@v1
        with:
          primary-key: ${{ secrets.PEAR_PRIMARY_KEY }}
          namespace: my-app
          target: dist
          dry-run: true

Set namespace to your chosen name and target to the repo-relative path of the directory you want to publish. The concurrency group prevents two runs from racing to commit ci/snapshot.json at the same time. The workflow starts with dry-run: true, and you switch it to false once a seeder is online.

timeout-minutes ends a run that waits for a peer that never comes. Without it, GitHub lets the job run for 360 minutes.

Commit the workflow and push it to main. That push starts the first run.

For the full list of inputs and outputs, see the pear-ci GitHub Action reference.

Dry-run firstCopy Anchor Link

With dry-run: true, the action computes and logs the file-by-file diff without writing anything to the drive or committing a snapshot—the same safety check as pear stage --dry-run. On an empty drive, a dry run needs no peer.

Read the diff in the Actions log. Look for the files you expect, no surprise additions (.DS_Store, editor swap files, secrets), and sensible byte counts.

Wire up the pear:// linkCopy Anchor Link

The dry run prints the drive key it stages to:

starting stage for key <drive-key>

That key is your app's pear:// link. Set it as the upgrade field so installed builds poll it for updates:

npm pkg set upgrade=pear://<drive-key>

This is the same upgrade link that the manual deploy flow sets—the only difference is that CI now stages to it for you. Because the key is deterministic, you only do this once.

Keep a seeder onlineCopy Anchor Link

Before the first real run, start a peer that holds the drive. On a machine that stays online, seed the link and leave it running:

pear seed pear://<drive-key>

The seeder downloads each release while a run stages it. Every later run, dry runs included, first syncs the drive from it up to the lengths in ci/snapshot.json, so keep it running for as long as you publish from CI. For higher availability, seed the link on more than one machine (see Seeding with pear seed).

Then set dry-run: false in the workflow, commit, and push. In the job log, Stage should end with all remote peers synced, and Commit snapshot to main should commit the updated ci/snapshot.json. Every later push to main then stages and publishes automatically.

If no peer with the drive is online, the log stops at one of these lines until the job times out:

• syncing <key> to length <n>: the run is waiting to sync the drive before it stages.
• waiting synced remote peers for key <drive-key>: the run has staged and is waiting for a peer to download the release. It commits nothing.

Start the seeder, then run the job again.

Producing the build to stageCopy Anchor Link

pear-ci stages whatever is in target—the action itself has no idea whether that directory came from a desktop or a mobile build. To build and sign a desktop directory on CI first, pair it with make-pear-app: one job produces signed, notarized distributables (see Build and sign desktop apps in CI), and pear-ci stages the assembled deployment directory to your stable pear:// link.

See alsoCopy Anchor Link

• pear-ci GitHub Action reference—every input, output, and the underlying CLI.
• Holepunch GitHub Actions—the other shared actions, including make-pear-app.
• Build and sign desktop apps in CI—build and sign the artifacts pear-ci stages.
• Deploy your application—the full manual flow with release lines, provision, and multisig.
• Ship your app—the type-along walkthrough of staging by hand.
• Configuration—the upgrade field and other package.json settings.
• Release pipeline—the conceptual picture of staging and OTA updates.
• Troubleshoot desktop releases—when an update does not reach peers.