Automate your policy
Keep the policy and release notes in step with your releases from EAS, GitHub Actions, scripts and coding agents.
The policy and release notes live in your repo (upwell/policy.json, upwell/releases.json) and
change at the same few moments in every release. The CLI turns each of those
moments into a command you can script. Every command takes --json and never prompts outside a
terminal, so the same commands work in CI and for coding agents.
Pin the CLI as a dev dependency so CI runs the version you tested:
npm install -D @upwell/cli
npx upwell --versionAfter an OTA update
eas update --json prints the update group it created. Feed it to releases add, so users (and App
Review) see what the update changed, then publish:
eas update --branch production --environment production --message "Fix checkout on iOS 27" \
--json > eas-update.json
npx upwell releases add --from-eas-update eas-update.json --kind fix --yes
npx upwell publish --yesThe id, platforms, runtime and date come from EAS, and the notes default to the update message.
--kind is always yours to give (fix, content or feature): it's what the update is called in
the app.
The first OTA update for a new runtime also moves the policy's OTA runtime. That strands
installs on the old runtime, so it needs --confirm:
npx upwell policy set ota-runtime 3.5.0 --confirm
npx upwell publish --confirmAfter a store release
Update latest once the build is live in the store (and rolled out, on Play), not when it's
built or submitted:
npx upwell policy set latest --platform android --version 3.5.0 --build 350 --released-at today --yes
npx upwell policy set latest --platform ios --version 3.5.0 --build 1 --released-at today --yes
npx upwell publish --yesRaising minimum stays a deliberate, separate step:
forced updates block everyone below it.
Not on build success
EAS Build hooks (eas-build-on-success) run when a binary is built, long before it's in users'
hands. Pointing latest at it then would prompt users to update to a version they can't
download yet. Run the commands above from the job that knows the release is live, or by hand.
Review in pull requests, publish on merge
Edit the files with the CLI (or by hand) in a branch, let the pull request show what changes, and publish when it's merged.
name: Upwell policy check
on:
pull_request:
paths: ['upwell/**', 'upwell.json']
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npx upwell policy validate
- run: npx upwell releases validate
# The diff against what's live, and who each risky change affects. Needs no token.
- run: npx upwell publish --dry-runname: Upwell publish
on:
push:
branches: [main]
paths: ['upwell/**', 'upwell.json']
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
# The merged pull request was the review, so --confirm accepts risky changes.
# Use --yes instead to make them fail here and publish those by hand.
- run: npx upwell publish --confirm
env:
GH_TOKEN: ${{ secrets.UPWELL_PUBLISH_TOKEN }}Publish once by hand first (npx upwell publish) and commit the upwell.json it writes: CI then
updates the same gist or repo instead of creating a new one.
| Target | UPWELL_PUBLISH_TOKEN |
|---|---|
| Gist | A personal access token with the gist scope. The workflow's own GITHUB_TOKEN can't write gists |
| Public repo | A fine-grained token with contents: write on that repo. If the policy repo is the repo running the workflow, use ${{ secrets.GITHUB_TOKEN }} and permissions: contents: write |
Coding agents
Agents can run the whole release flow above. Everything they need:
--jsonon every command prints exactly one JSON value on stdout:{ "ok": true, "data": … }or{ "ok": false, "error": { "code": "…", "message": "…" } }.- Without a terminal nothing prompts. Writes need
--yes; changes that affect installs fail withCONFIRMATION_REQUIRED(exit code 3) and list the affected installs inerror.risks, so the agent can ask you before re-running with--confirm. --dry-runon every command that writes.upwell explainanswers "what would a user on build X see?" with the app's own engine.upwell doctor --jsonfinds setup problems, each with acodeand afix.- The error codes and exit codes are stable.
Paste this into your app repo's AGENTS.md (or CLAUDE.md):
## App updates (Upwell)
The update policy and OTA release notes are `upwell/policy.json` and `upwell/releases.json`,
published to the URLs in `upwell.json`. Change them only with the Upwell CLI (`npx upwell …`,
always with `--json`), never by hand:
- After `eas update`: `npx upwell releases add --from-eas-update <eas update --json output> --kind fix|content|feature --yes --json`
- After a store release is live: `npx upwell policy set latest --platform <android|ios> --version <v> --build <b> --released-at today --yes --json`
- Then: `npx upwell publish --yes --json`
- To check what a user on a build sees: `npx upwell explain --platform <p> --build <b> --version <v> --runtime <r> --json`
- To check the setup: `npx upwell doctor --json`
If a command fails with CONFIRMATION_REQUIRED, show me `error.risks` and wait for my go-ahead
before re-running it with `--confirm`. Never raise `minimum` unless I ask for a forced update.