Preview branches and pull requests

A preview is a full copy of your site, built from a branch or a pull request, at its own address. Share it with a client or a colleague, check it on your phone, and merge only when you are happy. Previews never change your live site, and you choose who can open them (see Private previews).

Previews work for projects connected to GitHub (see Import from GitHub). They are on by default.

How previews are built #

<name> is your project's address name, the part before .zeloxa.app. For a project at my-shop.zeloxa.app:

• the branch redesign is previewed at redesign--my-shop.zeloxa.app;
• pull request #12 is previewed at pr-12--my-shop.zeloxa.app.

A pull request is built when it is opened, reopened, marked ready for review, and on every new push to it. Because its branch is also pushed, a pull request usually has both: a branch preview and a pr- preview of the same code.

Each address always shows the newest successful build for that branch or pull request. If a build fails, the address keeps showing the last good one.

What you'll see: on the Git tab, the preview's build with its log. The last line of a successful build is "Preview ready at https://redesign--my-shop.zeloxa.app (the live site is unchanged)."

Branch names in the address #

Branch names are turned into a safe address:

• lowercase, with anything other than letters and digits turned into a single hyphen: feature/New-Header becomes feature-new-header;
• cut to 40 characters;
• a branch named like pr-5 or dpl-7 gets br- in front (br-pr-5), so it never clashes with the addresses below.

Pinned links to one deployment #

Every deployment also has a permanent address of its own: dpl-<number>--<name>.zeloxa.app. Deployment #42 of my-shop is at dpl-42--my-shop.zeloxa.app.

Unlike a branch or pull request preview, a pinned link never moves to a newer build. Use it to show a client exactly the version they approved, or to compare two versions side by side. It works for any successful deployment, including ones that were live in the past. Find the number on the Deployments tab (#42).

On GitHub #

Commit status. Each commit Zeloxa builds gets a check named "Zeloxa Host – <project name>". It shows "Building…", then "Preview ready" (or "Deployed" for production) or "Build failed". Its Details link opens the preview, or the build log if the build failed.

Pull request comment. On a pull request, Zeloxa posts one comment with the preview address, a link to the build logs and the commit. Each new push updates the same comment rather than adding another. If the build fails, the comment says so and links to the logs.

What you'll see: a comment like "Zeloxa Host preview for My Shop is ready", with the preview link in a small table.

If you do not see the check or the comment, the Zeloxa app on GitHub may be missing permission for commit statuses or pull requests. Accept the updated permissions on GitHub when asked. Builds still run either way.

Previews never affect production #

• A preview build is never released to your live site or your custom domains, whether it succeeds or fails.
• A failed preview does not mark your project as failed.
• Previews only exist on zeloxa.app addresses. Your custom domains always show production.
• Preview builds get only the environment variables set for Preview. A variable set for Production only never reaches a preview build.

If the project is password protected (Settings → Password protection), previews ask for the same password too, after the preview sign-in if previews are private.

Previews are hidden from search engines #

Every preview and pinned link is sent with the header X-Robots-Tag: noindex, nofollow, so search engines do not list it, even if someone shares the link publicly. Your live site is not affected.

Hiding from search engines is not the same as private. To decide who can open a preview at all, see Private previews.

Private previews #

Settings → Preview protection decides who can open the project's preview addresses (<branch>--<name>.zeloxa.app, pr-<number>--<name>.zeloxa.app) and pinned links (dpl-<number>--<name>.zeloxa.app):

New projects start private. Projects created before this setting existed start public, so nobody lost access to a preview they were already sharing. Change it at any time.

Your production site (<name>.zeloxa.app and your custom domains) is never affected by this setting. To protect it too, use Password protection.

Only your organization's owner and admins can change the setting and manage access links. Every member can see them.

Make previews private #

1. Open the project's Settings tab.
2. Scroll to Preview protection.
3. Choose Make previews private.

What you'll see: the badge Private: team and access links, and the note "Previews are private. Visitors who aren't signed in now see a sign-in page."

The change reaches visitors within a few seconds.

What a visitor sees #

Someone who opens a private preview without access sees a plain, unbranded page: "This preview is private". It offers two ways in:

• Sign in with Zeloxa, for members of your organization. They sign in (or are already signed in to the dashboard), Zeloxa checks that they are a member of the organization that owns the project, and brings them back to the page they asked for. They stay signed in to that preview address for 12 hours.
• Have an access link? Open it, for everyone else. They paste the access link you sent them.

Someone signed in to Zeloxa who is not a member of your organization sees "You don't have access to this preview" instead, without the name of your organization or project.

Each preview address remembers its visitors separately. A member opening a second preview is signed in again automatically.

Share a private preview with an access link #

An access link lets someone outside your organization, such as a client, open the project's previews without an account.

1. In Preview protection, under Access links, type a Name (for example the client's name) and choose when it Expires: after 1, 7 or 30 days, or never.
2. Choose Create link.
3. Under Open on, choose the preview to send (the newest one is selected), then choose Copy.

What you'll see: "Your access link is ready. Copy it now: it won't be shown again." Only a fingerprint of the link is kept, so if you lose it, create a new one.

The link works on every preview and pinned address of the project, until it expires or you revoke it. Someone who opens it is let in on that device for up to 7 days (never past the link's expiry), then opens it again. To view another preview address, they paste the same link into that address's sign-in page.

A project can have up to 25 access links. The list shows when each was created, when it expires and when it was last opened.

Revoke an access link #

Choose Revoke next to the link, then Revoke link to confirm. The link stops working, and everyone who opened it loses access within a few seconds.

Sign everyone out #

Sign everyone out ends every visit at once: members sign in again, and people with an access link open it again. The links themselves keep working. This happens on its own, on every private project, whenever someone leaves or is removed from your organization, so a former member cannot keep viewing a preview they had open. Use the button when you want everyone to sign in again for another reason.

Make previews public again #

Choose Make previews public, then confirm. Anyone with a preview address can open it again. Access links are kept, and work again if you make previews private later.

Pull requests from forks are not built #

A pull request from a fork (someone else's copy of your repository) is never built. Its code would run with your project's environment variables and be published at your preview address. Only pull requests from branches in your own repository get previews.

To preview a contributor's change, push their branch to your repository yourself after reviewing it.

Turn previews off #

1. Open the project's Git tab.
2. Choose Edit settings.
3. Untick Build previews for other branches and pull requests.
4. Choose Save settings.

What you'll see: the repository card shows Previews off. Pushes to other branches and pull requests are no longer built. Pushes to your production branch still deploy.

Previews already built keep working at their addresses. A deploy hook on a non-production branch stops working while previews are off.

Previews are also not built while Deploy automatically on every push is off.

Good to know #

• One build per preview at a time. If a branch is pushed again while its preview is building, the newer push is not queued. Push again (or call a deploy hook) once the running build ends.
• Busy organization. When your organization already has two builds running, a preview push is skipped, not queued. Production pushes wait their turn instead.
• Skip keywords and watch paths apply to branch pushes too: a push with [skip ci] in its commit message, or one that changes nothing in the project's watch paths, builds no preview. Pull requests always build. See Skip a build.
• Closing a pull request or deleting a branch does not remove its preview. The address keeps showing the last successful build.

Related #

• What happens on each push
• Deploy hooks can build a preview branch on demand.
• Get a message when builds finish: webhooks and notifications