Brease Docs

Publishing and caching

What happens in your repository and on your host when someone publishes from Brease.

Every publish creates a release: a numbered, immutable snapshot of the site's content, tied to a git commit. A release is either content only or code and content.

Content-only releases

When nothing in the code changed, nothing is pushed to git. The new release goes live on the current commit, and the live site picks it up depending on the site's content refresh setting (Developer settings › Connections):

  • Revalidate (Next.js on Vercel, or any site that adds its own revalidate route): Brease calls the site's revalidate URL with the changed URLs. By default the URL is https://<domain>/api/brease/revalidate.
  • Redeploy (static builds, and every site on Cloudflare): Brease triggers a new build on the host. The site reads the new content during the build, so the change is live once the build finishes, usually in a minute or two.

Changes made on the dashboard (hiding, creating or deleting a page, redirects) are content-only releases that publish straight away.

Code releases

When the code changed:

  1. Brease commits the changes in a worktree, rebasing onto the production branch if it moved. A conflict stops the publish.
  2. It pushes to a temporary branch, brease/release-<site>-<N>, and waits for its GitHub checks (Vercel preview, GitHub Actions; up to 20 minutes). If a check fails, the production branch isn't touched.
  3. It pushes the commit to the production branch (a fast-forward, not a pull request). Branch protection that blocks the push fails the publish; setup checks for it, and so does Brease before preparing the editor.
  4. It follows the production deployment on the host. If a Vercel project doesn't promote automatically, the editor shows Waiting for approval in Vercel.
  5. If the deployment fails, Brease pushes a commit that restores the live release's code. The changes stay in the editor as unpublished.

Pushes made outside Brease are deployed by your host as usual. If one's deployment fails, Brease doesn't revert it by itself: the dashboard shows the failed deployment and offers Revert, which restores the code from before that push.

When the user has linked their GitHub account, commits are authored by them. Otherwise the Brease app is the author, with a Co-authored-by line for the user.

Drafts

A draft saves a chat's unpublished work for later. Its content is stored in Brease as a draft release. When it includes code, the code goes to a branch brease/draft/<chat> with a GitHub draft pull request, and the content is tied to that branch, so the branch's preview deployment shows both, including after a developer pushes a fix to the branch. A draft with content changes only has no branch, pull request or preview deployment until code is saved into it.

  • Merging the pull request on GitHub publishes it: the merge commit becomes a release with the draft's content merged onto the live content.
  • Closing the pull request closes the draft. Drafts also expire after 30 days without changes, except drafts open in an editor and drafts whose code conflicts were left for a developer.
  • When a draft is reopened, its content is merged onto the live content and its code is applied onto the current production branch. A code conflict can be left for a developer, who resolves it in the pull request.

Reverting

Restoring an old release creates a new commit on top of the production branch with that release's files (Revert to release N), plus a release with its content. History is never rewritten.

Commit pinning

brease-client sends the deployment's commit in the x-brease-commit header. It picks it up by itself from the build: VERCEL_GIT_COMMIT_SHA on Vercel, WORKERS_CI_COMMIT_SHA on Cloudflare Workers Builds and CF_PAGES_COMMIT_SHA on Cloudflare Pages. On a Brease draft branch it also sends the branch (x-brease-branch, from VERCEL_GIT_COMMIT_REF, WORKERS_CI_BRANCH or CF_PAGES_BRANCH). The delivery API then serves the newest release made for that commit or draft, or the live release when there is none. As a result:

  • A code release and its content go live together: the new deployment reads the new content, and the old one keeps reading the old content until Vercel switches over.
  • Preview deployments of a draft branch show the draft's content.
  • An old deployment that's promoted again reads the content it was built with.

Cloudflare's variables exist only during the build, so pages rendered at request time on Cloudflare read the live release. Pass commit to createBrease() to set it yourself, or commit: false to always read the live release.

Caching

The delivery API answers with Cache-Control: public, s-maxage=60, stale-while-revalidate=300, Vary: Authorization, x-brease-commit, x-brease-branch and an ETag. In Next.js, breaseFetch() tags every request with brease. The revalidateHandler() route purges that tag and the released paths.

brease-client also keeps the site and redirects in memory for a minute. The revalidate route clears that copy only in the server instance that received the call; other instances (serverless functions, edge regions) pick up the change within the minute.

Revalidate webhook

After a content-only release goes live, Brease sends:

POST /api/brease/revalidate
Content-Type: application/json
x-brease-timestamp: 1767225600000
x-brease-signature: 6f1c…

{ "siteId": "site_…", "releaseId": "…", "urls": ["https://example.com/about"] }

x-brease-signature is the hex HMAC-SHA256 of `${timestamp}.${rawBody}`, keyed with BREASE_REVALIDATE_SECRET. Reject requests older than five minutes. revalidateHandler() does all of this; implement it yourself only outside Next.js.

On this page