Previews

A preview is a short-lived environment that serves a branch at its own address, so a change can be reviewed before production. This page explains when a preview is born and when it goes away, how to protect it, how to let an automated tool through, how to create one on demand, and how to handle a pull request coming from a fork.

Concepts

• Preview: an environment of kind preview, attached to a branch. Every new commit on the branch is deployed to it.
• Branch address: the preview's stable address. Each deployment also keeps its own immutable address.
• Protection: what the preview asks of whoever visits it. The setting applies to all of the project's previews.
• Bypass token: a short-lived token that gets through the protection, for CI and end-to-end tests.
• Fork: a pull request opened from a third party's copy of the repository.

When a preview is born

Three paths create one:

1. A pull request opened from a branch that no rule in glowsoft.json sends elsewhere. Each update to the pull request redeploys its latest commit.
2. A push to a branch that a pattern sends to preview in glowsoft.json:

{
  "version": 1,
  "branches": {
    "production": "main",
    "patterns": [{ "pattern": "feat/**", "environment": "preview" }]
  }
}

1. An explicit request, from the console or with preview_manage (see below).

Without glowsoft.json, no push outside the production branch creates a preview: only pull requests and explicit requests do. See Git and automatic deployment.

A preview's variables follow the environment rules.

When it goes away

• When its pull request is closed or merged, unless another open pull request follows the same branch.
• After seven days without activity. Each push, each pull request update and each visit pushes the deadline back by seven days.
• When its branch no longer exists in the repository: a nightly inventory destroys it.
• At the deadline chosen for an on-demand preview (1 to 30 days), also pushed back by activity.

The immutable addresses of its deployments keep being served for their retention period, even after the preview is destroyed. On Vue d'ensemble (overview), the environments card shows each preview's planned deletion date.

Protect previews

Every preview carries noindex, whatever the mode. Environments that are not previews are not affected.

From the console

Open the project's Réglages (Settings), section « Aperçus » (previews), card « Protection des prévisualisations » (preview protection). Choose « Qui peut voir une prévisualisation » (who can see a preview), fill in the « Mot de passe partagé » (8 to 128 characters) or the « Adresses admises » (allowed addresses), then save. Saving closes every open visitor session: the card says so beforehand.

In « Membres du projet » mode, a visitor who is not signed in is sent to the console's Entrée dans une prévisualisation (preview entry) screen, which opens a single-use entry address (valid for one minute) and then a one-hour session.

Through an agent or the API

preview_protection_configure sets the mode, with the maintainer (maintainer) role or the cross-cutting security role. An agent cannot set public.

{
  "projectId": "prj_01JQ8ZK4M7NP2RSTVWXYZ34567",
  "mode": "addresses",
  "addresses": ["203.0.113.0/24", "2001:db8::/48"]
}

The password is never read back: the response only says passwordSet. Without password or addresses, the value already set stays. The widest range allowed is a /16 in IPv4 and a /48 in IPv6.

Bypass tokens

A token lets a CI pipeline or a test suite through a preview's protection, whatever its mode.

• It is valid for a single environment, for 24 hours at most.
• It is presented in the X-Bastide-Contournement header, never in an address. The edge strips it from the request before it reaches your application.
• It is shown once, at creation.
• Twenty active tokens at most per environment.

In the console, the « Protection des prévisualisations » card has a « Jetons de contournement » (bypass tokens) part: pick the preview, « À quoi il sert » (what it is for) and the « Durée, en heures » (duration in hours). Creation is reserved for people, through the [preview.token.create](/docs/reference/preview.token.create) operation; an agent revokes a token with preview_token_revoke, after which the edge refuses it within thirty seconds.

curl -H "X-Bastide-Contournement: bpt_..." https://<preview-address>/

An on-demand preview

To review a branch with neither a pull request nor a rule, open the project's Réglages, section « Aperçus », card « Prévisualisation à la demande » (on-demand preview). Enter the « Branche » (branch) and the « Durée, en jours » (duration in days, 1 to 30), then create it. The same action on an existing preview pushes its deadline back; another destroys it.

An agent does the same with preview_manage:

{
  "projectId": "prj_01JQ8ZK4M7NP2RSTVWXYZ34567",
  "action": "create",
  "branch": "feat/basket",
  "ttlDays": 7
}

Nothing is deployed at this point: the response returns environmentId, and the address is born with the first deployment, which you start with deployment_create on that environment.

Pull requests from forks

A fork's code belongs to a third party. It is never built on its own:

1. The pull request appears in the « Protection des prévisualisations » card, under « Demandes de fusion issues d'une bifurcation » (pull requests from forks), marked « Attend une autorisation » (awaiting authorisation).
2. A member with the maintainer role reviews the commit, then authorises it. The « Construire la demande n° ... ? » (build pull request no. ...?) dialog states what the authorisation commits to.
3. The authorised commit is built in an isolated environment, marked « Isolé · bifurcation » (isolated, fork): it receives no sensitive variable, neither its own nor any it would inherit. Its configuration is read from your repository's default branch, not from the fork.

The authorisation covers one specific commit, which must be the latest of the pull request. A commit pushed afterwards waits for its own authorisation (commit_non_autorise). The operation is [preview.fork.accept](/docs/reference/preview.fork.accept), reserved for people.

Limits per tier

At the cap, a new preview is refused, naming the cap and the tier. Closing a pull request or deleting a branch frees one. Each preview also consumes build minutes (see Builds).

Common errors

No preview screenshot is taken of a protected preview: this is expected, the screenshot would only show its gate.

See also: Git and automatic deployment, Environments and variables, Deploy, Deployment checks, Agent safety.

Report a mistake on this page