Proxy dynamic-hole requests or restrict this export

For any page containing a request-dependent node, the exported HTML is only a shell: server/publish/holeRuntime.ts fetches /_instatic/hole/<nodeId> from the page's origin. Under the documented separate-origin setup that request goes to the bucket or static web server, where no Instatic hole handler exists, and the swallowed failure leaves placeholder content permanently visible. Either limit this workflow to hole-free sites or document a proxy from the public origin to the CMS's hole endpoint, including the required cookie behavior.

AGENTS.md reference: AGENTS.md:L53-L53

Useful? React with 👍 / 👎.

Include locally hosted uploads in the deploy artifact

When a site uses the normal local media storage, this command copies only published/current, but server/publish/mediaPrefetch.ts deliberately preserves media URLs such as /uploads/abc-hero.png; the publish slot itself contains HTML plus generated CSS/runtime assets, not those upload files. The separate host will therefore return 404s for local images, variants, fonts, and public plugin assets unless the procedure also exports the required public upload objects or configures /uploads/ to reach their existing origin.

Useful? React with 👍 / 👎.

Configure clean-URL routing for bucket targets

On bucket/CDN targets that perform exact object-key lookup, extensionless public routes will not resolve: server/publish/staticArtefact.ts writes /about as about.html and /posts/hello as posts/hello.html, while visitors still request the extensionless paths. This recommended bucket setup does not add a rewrite, so the homepage may work while ordinary pages return the bucket's 404; document CDN/worker rewrites from extensionless paths to .html objects or change the exported layout to directory indexes.

AGENTS.md reference: AGENTS.md:L53-L53

Useful? React with 👍 / 👎.

Preserve the deploy repository during the destructive sync

After the one-time clone, ./ contains the repository's .git directory, but the publish slot does not. The local rsync --help defines --delete as “delete extraneous files from dest dirs,” so this command deletes .git before the following git add, making the documented workflow fail on its first publish. Sync through a protected staging directory or explicitly exclude/protect repository metadata.

Useful? React with 👍 / 👎.

Copy local media from the actual uploads root

With the standard local-disk adapter, media is written directly to join(UPLOADS_DIR, storagePath) and /uploads/<storagePath> is served by stripping /uploads before resolving against UPLOADS_DIR (src/core/plugins/mediaStorageRegistry.ts and server/router.ts). Therefore $UPLOADS_DIR/uploads/ normally does not exist, and this command copies none of the images, fonts, or variants that the deployed pages reference. The artifact must source those public paths from the UPLOADS_DIR root, excluding non-public trees such as published, or use the documented proxy alternative.

AGENTS.md reference: AGENTS.md:L292-L292

Useful? React with 👍 / 👎.

Account for signed-redirect object storage

External object storage does not always eliminate the cross-origin caveat: an adapter using servingMode: 'signed-redirect' stores /_instatic/media/<adapterId>/<storagePath> URLs, whose redirects are generated by tryServeMediaRedirect in server/router.ts. On the separate static origin described here, those media URLs still 404 unless /_instatic/media/* is proxied to the CMS; only public-url adapters can fall away as stated.

AGENTS.md reference: AGENTS.md:L292-L292

Useful? React with 👍 / 👎.

Route all CMS-backed public endpoints

When a published site contains a CMS-native form or an infinite loop—and even for the holes acknowledged here—the Step 3/4 configurations still proxy only media. src/modules/base/forms/formRuntimeJs.ts calls /_instatic/form/{challenge,submit}, server/publish/loopRuntime.ts calls /_instatic/loop/*, and server/publish/moduleJsBundle.ts emits /_instatic/module-js/*; these requests therefore hit the static host and 404, preventing forms from submitting and load-more behavior from working. Expand the compatibility list and proxy/CDN rules to cover every CMS-backed public route, including the hole routes.

AGENTS.md reference: AGENTS.md:L53-L53

Useful? React with 👍 / 👎.

Let real commit failures stop deployment

When git commit fails because of missing identity configuration, signing, a hook, or an I/O error—not merely because there are no changes—this || echo converts the failure into success and proceeds to push the previous commit. In an automated post-publish job, that can exit successfully while leaving the old site deployed. Check whether the index is unchanged before committing, and allow actual commit failures to abort the job.

Useful? React with 👍 / 👎.

Add the static site to PUBLIC_ORIGIN

When the deployed site contains a form, proxying /_instatic/form/* is insufficient: handlePublicFormRequest rejects the POST unless its browser Origin is accepted by originAllowed, and the browser preserves the static site's origin through the reverse proxy. Following this note and configuring only the private admin/CMS origin therefore makes every proxied form challenge and submission return 403; instruct operators to include both the CMS/admin origin and the deployed public origin in the comma-separated PUBLIC_ORIGIN value.

AGENTS.md reference: AGENTS.md:L292-L292

Useful? React with 👍 / 👎.

Make the 404 artifact requirement explicit

When a site has no enabled notFound template, publishSite deliberately skips writing 404.html, so the slot does not always contain this file. The nginx error_page example and the bucket/CDN fallback later in this guide both assume it exists, leaving such installations with a missing fallback or the host's default error response; make this statement conditional or require operators to create and publish a not-found template first.

AGENTS.md reference: AGENTS.md:L292-L292

Useful? React with 👍 / 👎.

Limit rollback claims to fully static exports

When the exported site uses holes or other CMS-backed runtime content, rolling DeployHQ back only restores the old files; it does not restore the CMS's published snapshot or publishVersion. Consequently, the old shell's hole requests carry an obsolete ?v= and handleHoleRequest replaces them with stale sentinels, while module-JS and forms still resolve against the latest CMS snapshot. Presenting rollback as a complete recovery path can therefore leave a rolled-back dynamic site blank or inconsistent; document that it is safe only for fully static output, or require a coordinated CMS rollback.

AGENTS.md reference: AGENTS.md:L340-L340

Useful? React with 👍 / 👎.

Route non-root trailing-slash URLs to the baked HTML file

For a page such as about, the publisher writes about.html, while the live router accepts both /about and /about/ by trimming trailing slashes. This rewrite sends /about/ to about/index.html, which is never produced, so valid trailing-slash page and data-row URLs 404 on the bucket; the nginx try_files example has the same gap. Redirect non-root trailing-slash requests to the canonical path or strip the slash before appending .html.

AGENTS.md reference: AGENTS.md:L340-L340

Useful? React with 👍 / 👎.

Make the introductory 404 artifact claim conditional

On sites without an enabled not-found template, publishSite does not write 404.html, so the opening compatibility statement still incorrectly promises that every publish slot contains one. This contradicts the corrected Step 1 guidance and can lead operators to configure a missing fallback; qualify this occurrence as conditional too.

AGENTS.md reference: AGENTS.md:L340-L340

Useful? React with 👍 / 👎.