Appearance

Manage deployments ​

This page covers the Deployments page and the three actions you'll reach for when something needs to change: Redeploy, Instant rollback, and Abandon.

Prerequisite: your first deployment exists.

Prompt for your agent

Copy this into Claude Code, Cursor or any agent that can run shell commands. Redeploy, rollback and abandon are clicks in your browser on a repo project; on an uploaded site with an agent key the agent publishes the fix itself.

text
Read https://docs.stasho.xyz/guides/manage-deployments.md. My Stasho project <project> is
serving a bad build. If it is an uploaded site and my agent key (in STASHO_AGENT_KEY, never
ask me to paste it) can publish, publish the fixed version and tell me the new url. Otherwise
tell me, in the page's words, which action to click (Redeploy, Roll back to this, or
Abandon) and what the confirmation will show, then verify: fetch the URL I give you and
confirm the content is the build we wanted. Never ask for my wallet key.

The Deployments page ​

Your project's Deployments tab lists every build: status, commit and message, branch, age, and a LIVE badge on whichever build your domains currently serve. Filter by status or branch; click a row for the full detail — every deployment has its own shareable URL (/projects/<id>/deployments/<deploymentId>).

The Deployments page in its wide layout: on the left, branch and status filters above a list of three builds, the selected one highlighted and carrying a green LIVE ON ALMANAC.APPS.STASHO.XYZ badge; on the right, the selected build's detail pane with a Summary block (framework nextjs, branch main, build time 41s, created and finished timestamps), a public on-chain records block linking its creation POST and final status messages, an encrypted Build metadata block, and a collapsed Verify on-chain expander.
The Deployments page on a wide screen: the list on the left, the selected build's detail on the right.

Every build names who made it. A build published by an agent key reads Published with key "…" beside its message, and the project Overview reads Created with key "…" on a site a key created; a build from a push or a Redeploy carries its commit instead. The key's name is the attribution, so name keys after what holds them ("Worker prod", "Claude chat").

The detail pane shows the build's facts (CID, framework, branch, build duration), its source (commit, message, error output if it failed), and its on-chain record:

  • Verify on-chain — a collapsed expander showing the chain of on-chain messages behind this deployment, each linking to a public explorer. See Your data on-chain for what you can verify.
  • Raw JSON — the unprocessed on-chain messages, for the skeptical.

Redeploy ​

What it does: builds and publishes the latest commit on your production branch, without you pushing anything. Note it's not a re-run of an old build — if the branch has moved since the last deploy, you get the new commits.

When to use it: after a failed build you've since fixed, after changing environment variables or build settings, or any time you want a fresh build without an empty commit.

Click Redeploy on the project Overview. The button dispatches the workflow and waits for the new deployment row to appear — GitHub's runner queue can be slow, so after ~30 seconds you'll get a link to the Actions run for reassurance. If the button reads Re-authorize instead, a deploy write was blocked pending a signature from you — see Keys & authorizations.

Instant rollback ​

What it does: re-points your live site to a previous build, instantly, with no rebuild. Every past build is still pinned on IPFS at its own CID — rollback just changes which one your domains serve.

  1. On the Deployments page, pick any previous live build and click Roll back to this
  2. The confirmation dialog shows exactly what will change — each attached domain and the CID it will serve — plus a Preview this build link so you can eyeball the target before committing
  3. Confirm. Domains re-point in roughly 15 seconds

After a rollback, the serving build shows a LIVE · rolled back badge with an Undo rollback button that re-points back to the latest build.

A rollback is not a pause. The next push to your production branch (or Redeploy) builds and publishes normally, and your domains serve that new build. Roll back to buy time while you fix the bad commit — then push the fix.

Only builds that completed (live, with a pinned artifact) can be rolled back to — a failed build never produced anything to serve.

Abandon ​

What it does: marks an in-flight deployment as failed, immediately and permanently. Offered on the deployment's detail page (the Overview's pipeline card links there with View deployment) while the deployment is in flight: anything not yet live or failed.

Your site is unaffected — it keeps serving the last good build. The app also tries to cancel the GitHub Actions run, but even if the workflow finishes on GitHub's side, the abandoned deployment stays failed and nothing gets published from it.

When to use it: a deploy is stuck and you want to clear it now instead of waiting — note that anything stuck in-flight for 30+ minutes is auto-failed for you anyway.

Verification ​

  • After Redeploy: a new deployment row appears and walks the pipeline to live
  • After Rollback: the target build wears the LIVE badge, and your domain serves it (allow ~15s, longer if the domain shows FINALIZING — see custom domains)
  • After Abandon: the deployment reads failed and the previous build still serves

Working with an agent ​

On an uploaded site, "redeploy" is publishing a new version over the agent API, and an agent with a publish key does it itself: the response carries the new url, and attached domains switch within a few minutes. Rollback and abandon are yours in every case, and so is everything on a repo-connected project: the three actions above are buttons in your browser, and no agent key reaches them.

What the agent hands you, in these words:

text
Open the project in the Stasho dashboard. To build the latest commit: click Redeploy on the
Overview. To serve an earlier build instead: open Deployments, find the build with commit
<sha>, open its ⋮ menu (or click the row) and choose Roll back to this; check the dialog lists
your domains and the build's CID, then click Roll back. To clear a stuck deploy: click View
deployment on the Overview's pipeline card, then Abandon, and confirm. Tell me when the build
wears the LIVE badge (or its detail reads Failed, for Abandon), and paste me the CID the
rollback dialog showed.

How the agent verifies it afterwards. The deployment's own URL is content-addressed, so a fetch proves which build is served:

bash
curl -sI https://<cid>.ipfs.aleph.sh/ | head -1
curl -s https://<your-host>/ | grep -c '<text only the wanted build contains>'

The first line confirms the build exists on the gateway; the second confirms your domain serves it. Pick a marker the wanted build contains and the bad one does not, such as a version string or a changed heading, by fetching both builds' gateway URLs first. A miss on the domain right after a rollback or redeploy is the gateway catching up (FINALIZING), not a failed action. On an uploaded site the agent can also read the site: latestDeployment.status reads live and url is the version being served.