Start by inspecting get_deploy for the existing numeric deploy ID. Record its site, sequence, environment, status, warnings, and any returned live URLs. A lost response or a slow pipeline does not mean another deployment is necessary.
Check the artifact#
Build the editable Astro source and package the contents of its output directory. index.html belongs at the ZIP root, alongside required assets. Include the CMS manifest and private templates when the site uses them. Exclude credentials, dependency folders, and unrelated archives.
A ZIP containing dist/index.html rather than index.html has the wrong root layout. A client-only shell can deploy but trigger spa_shell and poor retrieval. An omitted image or stylesheet remains omitted from the new artifact.
deploy_files also creates a fresh artifact from only its supplied files. It does not merge changed files into the previous release. Use it only when the entire required tiny artifact fits its 512,000 decoded-byte ceiling; use the ZIP workflow for a complete normal website.
Recover the existing upload#
| Observation | Action |
|---|---|
uploading, artifact already uploaded |
Finalize that deploy ID. |
no_artifact, saved URL still valid |
Upload the binary ZIP to that exact URL, then finalize the same ID. |
| Lost/expired URL, artifact may exist | Try finalizing the existing upload before starting another. |
| No artifact and no usable upload URL | Start a replacement deploy on the same site within remaining quota. |
too_large at finalization |
The oversized object was deleted; reduce the artifact before re-uploading. |
failed with a usable artifact/URL |
Correct the cause and use supported re-upload/re-finalization on that record. |
queued or another processing state |
Poll using retry_after_seconds; do not re-finalize. |
The signed URL is private and lasts 900 seconds. Send actual ZIP bytes using HTTP PUT, not JSON or base64 text. Inspect upload status before finalization. Keep size under returned max_bytes and preserve the artifact checksum when verifying integrity.
Check release routing#
A deployment can be live in staging while production still serves an earlier release. Inspect the site's release workflow and deployment pointer flags, then verify live_urls. Explicit deploys require a supported destination. Staging/both need an active release workflow; production in that workflow needs an active custom domain.
If the expected content is absent, compare the source build, artifact, selected environment, and actual public URL. Inspect the response after ordinary cache propagation rather than immediately rebuilding an identical artifact. CMS text may be republished independently of the static source.
Verify recovery#
Read every actionable warning, including skipped pages, CMS collisions, and social-preview problems. Open key pages and assets, confirm the new factual content in HTML, and test a meaningful chat response. Record the final deploy ID/sequence and destination.
For exhausted quota or expired guest access, preserve source and use account recovery. For a persistent platform failure, send support the safe deploy identifiers and exact error; never include the signed upload URL.