Hosted previews
Laimonade gives each working branch a URL on Cloudflare Pages or a Fly.io app, attaches it to the backlog item and the pull request, and removes it when the work is merged.
Last reviewed · maintained by Founder
What is a hosted preview?
A running copy of one branch that a tester can open, instead of reading the pull request. When a coding agent or a person pushes a branch for a backlog item, Laimonade builds that branch on your own Cloudflare or Fly.io account and records the URL on the item.
The URL appears in three places:
- On the item. The card shows a Preview ready chip that opens the preview, and the item detail lists each preview with its status (building, ready, failed or expired), the commit it was built from and when.
- On the pull request. One comment per preview, in the form Preview: URL · built from commit at time. It is edited in place on every rebuild, so a branch pushed ten times leaves one comment.
- In the In Review notification that goes to the item's testers, next to the pull request link.
get_backlog_item returns the same list as previews, with url, status and sha, so a
coding agent can read it too.
Which branches get one?
A branch gets a preview when all three hold:
- Its name starts with your branch prefix,
laimon/by default (Settings, Development). Pushes to any other branch are ignored. - The 24-character item id follows the prefix, as in
laimon/<item id>. That id is how the preview is attached to the item. - The repository has a preview kind other than No preview under Integrations.
Work on an item that is already Done does not get a new preview.
Setting it up
Both providers use the connections you already made in Integrations. Connect Cloudflare, Fly.io or both first, then open the Hosted previews card and choose, for each tracked repository, what to build.
The repository settings are:
| Setting | Applies to | Meaning |
|---|---|---|
| Preview kind | both | Cloudflare Pages, Fly app or No preview. |
| Build command and output directory | Pages | For example npm run build and dist. Both are required. |
| Pages project | Pages | The project the repository already deploys to. Optional when the repository is bound to a Pages project in the Cloudflare card. |
| API base env var | Pages | The build-time variable that receives the back-end preview URL, for example VITE_API_URL. Optional. |
| fly.toml path | Fly | Where the fly.toml is in the repository. Required. |
| Env group | both | A name for your own reference. |
| Secrets | both | Environment variables for the build (Pages) or the app (Fly), one NAME=value per line. They are stored encrypted and are never shown again; only the names are listed. NAME= removes one. |
| Time to live | both | 1 to 30 days, 7 by default, counted from the last push. |
Only owners and administrators can change these settings.
Cloudflare Pages
Two modes, chosen automatically for each push:
- Cloudflare builds it. When the Pages project is connected to the same GitHub repository, Cloudflare builds the branch itself and Laimonade reads the finished deployment back. This is the closest match to production, because it is the same build.
- Laimonade builds it. When the project is not connected to the repository, or the preview has to be pointed at a back-end preview, a short-lived builder machine clones the branch at the pushed commit, runs your build command and uploads the output directory to the project under the branch name.
The Cloudflare token needs permission to read and edit Pages on the account, because removing a preview deletes the deployments of that branch.
Fly.io
Laimonade creates an app named after the repository and the branch, for example
my-api-laimon-<item id>, in your organisation, imports your secrets, deploys the branch
and sets every machine to stop when idle and start on the next request. The first request
after an idle period is slower while the machine starts.
Use a Fly organisation token. A token scoped to a single app cannot create or destroy apps. Laimonade refuses to build into, or destroy, an app that is bound to a repository in the Fly card as its production app.
The deploy is labelled with the commit, the same convention production deploys use:
fly deploy --image-label git-$(git rev-parse HEAD) --build-arg GIT_SHA=$(git rev-parse HEAD)
That label is how Laimonade ties a Fly release to a commit, and therefore to the item.
When a front-end and a back-end belong together
If both repositories have previews and the front-end names an API base env var, the front-end preview of an item is built with the back-end preview URL of the same item. When the back-end becomes ready after the front-end, the front-end is rebuilt. Previews of different items are never wired together. This build is always made by Laimonade rather than by Cloudflare, because a Pages preview variable is shared by every branch of the project.
When is a preview removed?
Whichever happens first:
- the pull request is closed or merged;
- the branch is deleted;
- the item reaches Done or is archived (checked every two minutes);
- the time to live passes without another push.
Removal destroys the Fly app or deletes the Pages deployments of the branch. If your provider refuses the request, the preview stays listed and removal is retried.
What happens when a build fails?
The preview shows Failed with the first line of the error. Laimonade files a bug titled Preview build failed: repository@branch carrying the end of the build log, one open bug per branch, and the pull request comment shows the same tail. The next successful push replaces the failure.
Limits
- A build that has not finished after 20 minutes is stopped and reported as failed.
- A pull request is commented once Laimonade has seen it opened. A preview that finishes before the pull request exists is commented as soon as the pull request opens.
- A preview is only as private as the provider URL. Pages and Fly URLs are not access-controlled by Laimonade; put your own access rule in front of anything sensitive.
- Machine time spent building is charged to the project's coding budget and appears in its usage. A preview that is idle costs what Fly or Cloudflare charge your account for it.
- Secrets for a preview are held in a builder machine's environment for the length of one build.