Skip to content

Computer use for the Pi coding agent — Windows apps, browsers and desktops through native UI trees, screenshots and real input.

6.6 KB
Raw Blame

Develop and release Pi Agent Computer Use

Feature branches merge into develop. Ready changes merge into main through a pinned promotion PR. A versioned release starts from main and freezes it until the package is published and main has been merged back into develop, or the unpublished release is canceled. develop stays open throughout. The flow follows Pi Agent IDE, adapted to npm and one package.

Workflows

Workflow Trigger What it does
CI (ci.yml) Push and PR The Validate job runs typecheck, unit and integration tests. On a PR to main it enforces the release freeze. On a release PR it also builds the candidate archive.
Start release (release-start.yml) Manual, on main Creates release/X.Y.Z with the version and changelog section, then opens its PR to main.
Publish to npm (release.yml) Manual, on main Verifies the merged release PR and its candidate run, publishes that exact archive after approval, tags it and creates the GitHub release, then synchronizes develop.
Cancel release (release-cancel.yml) Manual, on main Closes an unpublished release PR and deletes its branch.
Synchronize main into develop (sync-develop.yml) Push to main Merges main into develop unless a release is active.

The scripts behind them live in scripts/release/.

Promote to main

Choose the release cut by its full develop commit SHA. Create a branch such as chore/promote-X.Y.Z from that commit and open its PR to main. Keep the branch unchanged while CI runs, then squash-merge it. Check that Synchronize main into develop succeeds before starting the release. Squash merges make the histories of main and develop diverge, so a failed synchronization must be fixed before the next promotion.

Start a release

Run Start release on main with an unused X.Y.Z and finished release notes. It refuses a version that npm already has, an existing tag and a second active release. It sets the version in package.json and package-lock.json, adds ## X.Y.Z — date with the notes to CHANGELOG.md and opens the release PR.

A branch named exactly release/X.Y.Z is the freeze marker. While it exists, the Validate check rejects every PR to main except the release PR and fix/release-* PRs labeled release-fix. Review the fix itself: the label is not proof that a change is a fix. After a fix merges into main, rebase the release branch onto it with --force-with-lease and wait for a new candidate run.

Release candidate

CI on the release PR runs the normal checks, then scripts/release/build-candidate.ts:

  1. Packs the package twice with npm pack (prepack fetches and hash-checks the pinned native runtime) and fails if the archives differ.
  2. Installs the archive the way pi install does: npm install <archive> --prefix <root> --legacy-peer-deps.
  3. Checks the installed manifest: every pi.extensions entry exists and every pi.skills root holds a skill.
  4. Runs test/installed-package.integration.test.ts against that install in real Pi, standalone and with the installed Pi Agent IDE.
  5. Records the PR, head, tested base, tree, run and archive hashes in candidate.json and keeps both files as the release-candidate artifact.

To rehearse packing and installation locally, run node scripts/release/build-candidate.ts --local. A local candidate is never published.

Squash-merge only a release PR whose candidate passed. Keep the release branch until publication and synchronization finish.

Publish

Run Publish to npm on main with the merged release PR number and the ID of its successful CI run. With publish: false it only verifies: the PR merged from release/X.Y.Z, the run is CI for that PR head, the squash commit has the tested tree on the tested base, main has not moved except for release infrastructure, and the downloaded archive matches the recorded hashes. With publish: true it then waits for approval of the protected npm environment and publishes the downloaded bytes with npm publish --provenance through npm Trusted Publishing. It never rebuilds the archive. A retry cannot replace a tag or publish different bytes under an existing version.

After publication the finish job waits until the registry serves the version, compares its integrity with the candidate, merges main into develop and deletes the unchanged release branch. If develop moved during the push or the merge conflicts, the branch stays and main stays frozen. Resolve the conflict and rerun the same publication.

To abandon an unpublished release, run Cancel release with the version and the confirmation cancel. If its PR already merged, revert it on main first. A published or tagged version cannot be canceled.

One-time setup

The repository owner configures these before the first release:

  • Make the repository public and create main from the commit chosen for 0.1.0.
  • Protect main: no direct pushes, PRs require the Validate check.
  • Install a GitHub App on this repository with Contents and Pull requests write access. Store its ID and private key as the Actions secrets RELEASE_APP_ID and RELEASE_APP_PRIVATE_KEY. The App pushes release branches, develop merges and branch deletions.
  • Create the npm Actions environment with required reviewers.
  • Create the release-fix label.

Publish the first version

npm cannot attach a Trusted Publisher to a package that does not exist yet, so 0.1.0 goes through the normal candidate flow and is then published by hand from the verified archive:

  1. Run Start release with 0.1.0 and its notes, wait for the candidate run and squash-merge the release PR.
  2. Run Publish to npm with publish: false. It keeps the verified archive as the release-0.1.0 artifact.
  3. Download that artifact (gh run download <run> --name release-0.1.0), check that sha512 in candidate.json matches the archive, and publish it: npm publish pi-agent-computer-use-0.1.0.tgz --access public.
  4. Attach the Trusted Publisher: npm trust github pi-agent-computer-use --repo alexshpunt/pi-agent-computer-use --file release.yml --env npm (npm 11.10 or newer). A new relationship expires if no trusted publish succeeds within two days, so later versions should follow soon or the relationship is recreated.
  5. Run Publish to npm again with publish: true and the same PR and run. It finds 0.1.0 in the registry with the candidate's integrity, creates the v0.1.0 tag and GitHub release, and synchronizes develop.

Every later version publishes through the workflow.