Published on
How do Zenifra Preview environments work for each pull request?
A Preview environment is a temporary copy of your HTTP project, with its own URL, running the version in a pull request without touching the main application. On Zenifra, projects with a GitHub or Forgejo source create and update the preview on every push to the pull request and remove it when the pull request closes or the expiration time runs out, billed hourly in Brazilian reais at the project plan’s price.
What a Preview environment is on Zenifra
A Preview environment is a temporary copy of your HTTP project, with its own URL, running the version in a pull request without touching the main application. On Zenifra, it is created when the pull request opens, updated on every push, and removed when the pull request closes or the expiration time runs out.
The documentation defines a preview as temporary execution capacity of the primary project, with its own lifecycle, storage, and billing, plus a URL when the project’s exposure allows it. In practice, it solves a problem every reviewing team knows: the reviewer reads the diff but never sees the change working. With a preview, the reviewer opens an address, clicks through the changed flow, and comments on the pull request based on what they saw rather than what they imagined.
There are two ways to create previews. The native path serves projects with a GitHub or Forgejo repository source and needs no workflow, API key, or image in the repository: Zenifra receives the pull request events and builds the commit with the runtime and commands the project already uses. The second path is the official Zenifra GitHub Action, for teams that already build a container image in CI and want to operate the preview explicitly, including projects without a GitHub source.
One point shapes the rest of this guide: a preview is not a copy of production data. It inherits the primary project’s environment variables, so it may point to the same database, queue, or bucket, and it starts with empty storage. Understanding that inheritance is what separates a useful preview from one that writes to real data by accident.
How Preview works per pull request
In the native flow, you pick a target branch, for example main. Pull requests created in the project’s own repository and aimed at that branch join the flow; the opened, reopened, and synchronize events create or update the preview identified as pr-<number>. The edited event re-evaluates the pull request when its target branch changes, creating, updating, or removing the preview according to its new eligibility, and closed removes the matching preview.
Pull requests aimed at another branch and pull requests from forks are left out. Pull requests already open before activation are not imported automatically; they start counting on the next relevant event, such as a new push. Each pull request keeps the same identity across updates, and reopening a pull request with the same key recreates or reactivates the same logical identity, keeping the URL whenever possible.
The preview target branch is independent of the primary update mode. It defines which pull requests get a preview and does not change the branch used to update the main application, which keeps its own version while the preview is created or updated. On GitHub, when the preview of a pull request opened with automatic previews on becomes available, Zenifra posts a single comment on the pull request with the address and time to live; later pushes do not repeat the comment.
Behind the scenes, each operation goes through public states you can follow: accepted, reserving, provisioning, and updating until it reaches available on a create or update, and deleting until deleted on a removal; failed ends the operation with a public message. Duplicate deliveries and idempotent retries are safe: the same key reuses the same environment and does not create copies.
How to turn on previews in the Console, step by step
The primary project must be on a plan that offers Preview environments. On GitHub projects, the GitHub account must be connected to the organization and the repository reachable by the project. On Forgejo projects, the connection must use a token with write:repository and an account that administers the repository hooks, because the hook is what delivers pull request events.
On GitHub there is a permission detail that often goes unnoticed: the Zenifra GitHub App needs the Pull requests permission (read and write) to receive the events and comment the address. Installations made before that permission keep deploying the main application but do not create previews until someone approves the update on GitHub. Installations that approved read-only access create previews normally, without the pull request comment.
To approve, a person with admin access to the account or organization opens GitHub settings under GitHub Apps (on personal accounts, Applications and then Installed GitHub Apps), chooses Configure on the Zenifra app and, on the update notice, Review request and Accept new permissions. After that, the next pull request event, such as a new push, creates or updates the preview; the address comment applies to pull requests opened after the approval.
- Open the Preview Environments section on the primary project page and choose Configure previews.
- Turn on Enable Preview Environments.
- Turn on Enable automatic GitHub previews (or Enable automatic Forgejo previews).
- Choose the Preview target branch, for example main.
- Set Default expiration (hours), Maximum expiration (hours), and Active environment limit for this project.
- Open or update a pull request to that branch and follow the preview creation.
Configuring previews requires the project.preview.configure permission, through a user session or an organization API key. If you turn off automatic previews or Preview environments, change the target branch, or disconnect the repository, the affected native previews are removed and pending deployments are no longer valid. The main application is not affected by that cleanup.
Temporary URLs, expiration, and automatic cleanup
Each preview has its own address, separate from the production URL. The illustrative demo on the Preview page shows the main application at https://loja.clients.zenifra.com and the preview for pull request 2 at https://loja-pr-2.clients.zenifra.com, with sample data. Always treat the address posted in the pull request comment or shown in the Console and the API as the source of truth, because the URL is returned when the preview becomes available.
The default time to live (TTL) is 24 hours and can be set between 1 hour and 168 hours, that is, up to 7 days after the last update. A successful create or update renews the expiration; duplicate deliveries and retries do not extend it just by repeating. If the closing workflow does not run, Zenifra removes expired previews automatically, including stopped ones.
Cleanup happens in four situations: the pull request closes (native flow), the expiration runs out, the primary project is deleted (all previews go at once), or you turn the feature off, change the target branch, or disconnect the repository. On removal, compute and storage billing ends at that moment and the preview address is released.
Active environments are limited at two levels, and the lower one wins. An organization can have up to 10 active previews at once, and a primary project up to 2. Creating beyond the limit ends the operation as failed with a public message; the Action fails the job. To raise the organization limit, the documentation says to email support@zenifra.com with the organization name and access email, current usage, and the desired limit with the reason.
| Rule | Documented value |
|---|---|
| Default expiration (TTL) | 24 hours |
| Configurable TTL range | 1 to 168 hours (7 days) |
| Active previews per organization | up to 10 at once |
| Active previews per primary project | up to 2 at once |
| Preview key | 1 to 100 characters (A-Z, a-z, 0-9, ., _, and -), with at least one letter or number |
| Default key on a pull request | pr-<number> |
| Action maximum wait (WAIT_TIMEOUT) | 1s to 15m, default 10m |
Variables, database, and storage in a Preview
Every preview inherits, inside the platform, the variables configured on the primary project, on each create or update. Values are never exposed through the API, the Console, or the Action, and never show up in outputs, the Job Summary, or logs. Variables managed by Zenifra are regenerated for the preview. The preview also inherits the port, exposure, and access rules needed to run the application, as well as the plan.
The consequence is direct: if the primary project’s DATABASE_URL points to the production database, so does the preview. The same applies to queues, buckets, and external APIs. The Preview page states it plainly: Preview does not create a database copy, and inherited variables may point to the same database, queue, or service. A destructive migration running in the preview’s start command, or a test that creates orders, hits real data.
What is not inherited or created today: data in databases, queues, buckets, and other services; custom domains; and custom image startup commands. The preview’s storage is new and starts empty. If the application depends on seed data, plan test data or a safe source for validation.
A pattern that works with these rules is enabling previews on a staging project rather than on the production project. You create a second HTTP project from the same repository, with variables pointing to a test managed database, and turn on Preview environments there. Previews inherit that project’s variables and only write to the test database. Once the change is approved and merged, the production project deploys through the update mode you already use. Combined with migrations compatible with two application versions, this keeps production out of reach of tests.
Previews from an image with the GitHub Action
If your CI already builds a container image, the official zenifra/action-zenifra-deploy GitHub Action creates, updates, and removes previews explicitly. This flow is independent of the native one and also works for projects without a GitHub source. The Action needs the organization API key stored in a GitHub secret and a ready image, usually exposed as a repository or organization variable.
On a pull_request event, the Action uses pr-<number> as the key when PREVIEW_KEY is not set; outside pull requests, the key is required. With PREVIEW_ACTION=auto, a closed pull request triggers removal, and in that case the image can be omitted. The Action waits for available on an upsert and deleted on a removal, and returns the outputs preview_id, preview_url, expires_at, operation_id, and preview_status. The preview always uses the primary project’s plan: there is no PREVIEW_PLAN and no separate price.
The minimum key is scoped to the primary project: project.read to read the project, project.preview.read to list, project.preview.deploy together with project.env.read (or project.image.update) to create or update, and project.preview.delete to remove. Without reading variables, creation returns PREVIEW_ENV_ACCESS_REQUIRED, because the preview inherits variables. Use only one flow per key: if a native preview already uses pr-<number>, the Action gets GITHUB_PREVIEW_KEY_OWNED, and the reverse blocks the native run.
- name: Zenifra preview
- on: pull_request with types: [opened, synchronize, reopened, closed]
- permissions: contents: read
- uses: zenifra/action-zenifra-deploy@v0.0.5
- with: PROJECT_ID: ${{ vars.ZENIFRA_PROJECT_ID }}, API_KEY: ${{ secrets.ZENIFRA_API_KEY }}, IMAGE: ${{ vars.ZENIFRA_PREVIEW_IMAGE }}
- with: PREVIEW: true, PREVIEW_ACTION: auto, PREVIEW_TTL: 24h, WAIT_TIMEOUT: 10m
To test a branch or version outside a pull request, the documentation includes a workflow_dispatch workflow where you enter preview_key and choose upsert or delete. Do not reuse the same key for changes that must exist at the same time: each key is a single logical environment.
How much a Preview environment costs
A preview uses the primary project’s plan and is billed hourly, in Brazilian reais, while it is active. The hourly price comes from the plan’s public catalog; there is no separate Preview plan catalog, and the preview payment mode is always hourly, even if the primary project is on a monthly or yearly contract. The calculator estimates the cost as the number of previews times the active hours of each times the plan’s hourly price.
The figures below use the catalog at https://api.zenifra.com/v1/project/plans checked on 11/06/2026, where prices are in cents: Static 1 (R$ 0.01/h), Basic 5 (R$ 0.05/h), Premium 11 (R$ 0.11/h), and Premium Plus 22 (R$ 0.22/h). A preview that lives 24 hours on Basic costs 24 × R$ 0.05 = R$ 1.20. A preview that lasts a full week, at the maximum TTL of 168 hours, costs 168 × R$ 0.05 = R$ 8.40. A team that opens 10 pull requests a month, each with a preview active for 30 hours, adds up to 300 hours: 300 × R$ 0.05 = R$ 15.00.
Two habits keep the bill predictable. The first is the TTL: a forgotten preview lives until it expires, so a short window, such as the 24-hour default, caps the cost of stalled pull requests. The second is the project’s active environment limit, which you set in the Console and which never exceeds 2 per project. The preview cost API returns amounts accrued from hourly snapshots, the pending amount, and an estimate until expiration, which is not a final charge.
If the organization has pending payments, preview creation returns ORGANIZATION_BILLING_BLOCKED until it is settled. The preview cost comes out of the same organization credit used by applications, databases, and AI, paid in reais by PIX or boleto, with the card as a backup for postpaid charges.
| Project plan (price/h) | 1 preview for 24 h | 1 preview for 168 h | 300 preview hours a month |
|---|---|---|---|
| Static (R$ 0.01/h) | R$ 0.24 | R$ 1.68 | R$ 3.00 |
| Basic (R$ 0.05/h) | R$ 1.20 | R$ 8.40 | R$ 15.00 |
| Premium (R$ 0.11/h) | R$ 2.64 | R$ 18.48 | R$ 33.00 |
| Premium Plus (R$ 0.22/h) | R$ 5.28 | R$ 36.96 | R$ 66.00 |
| Business (R$ 0.86/h) | R$ 20.64 | R$ 144.48 | R$ 258.00 |
These amounts assume one environment at a time, as the calculator does, and cover compute. The preview’s storage has its own billing, which also ends at the moment the preview is removed.
Team review flow and permissions
The real gain from Preview shows up in the review flow. Whoever opens the pull request does not need to send screenshots or record a video: Zenifra’s comment carries the address and the time to live. Reviewers open the URL, test the flow, return to the pull request, and ask for changes; every push updates the same preview with the same identity. Product, design, and support can validate the change without installing anything, as long as they have the address.
On Zenifra, each person joins the organization with their own login, with owner, assistant, or member roles and permissions per resource and action, scoped per project. Preview permissions are separate: project.preview.read to view, project.preview.deploy to create and update, project.preview.delete to remove, and project.preview.configure to change settings. That lets you grant viewing and publishing of previews without granting billing access.
There is no automatic promotion from Preview to the main application. After validation, the version reaches production through the flow configured on the primary project: with Automatic by branch, the merge deploys; with By Tag or By Release, the tag or release deploys. That keeps a single path to production and prevents a test environment from becoming production by mistake.
| Action | Minimum permission on the primary project |
|---|---|
| Read the primary project | project.read |
| List previews and view details | project.preview.read |
| Create or update a preview | project.preview.deploy and project.env.read (or project.image.update) |
| Remove a preview | project.preview.delete |
| Change Preview settings | project.preview.configure |
Comparison with Vercel, Render, Railway, and Heroku
All four platforms offer per-pull-request environments, with different models. The table summarizes what their official pages say, checked on 11/06/2026. Vercel creates Preview Deployments on every push to a non-production branch, on pull requests, and from the CLI without --prod, with branch-specific and commit-specific URLs, and each environment can have its own variables. Render recreates services, datastores, and environment groups per pull request on the Pro workspace plan or higher, without copying data. Railway creates a temporary environment per pull request, removed on merge or close. Heroku uses Review Apps, which depend on Pipelines, the GitHub integration, and an app.json file.
The most relevant difference for anyone testing with data is the database. Render and Heroku create new datastores and add-ons for each preview and offer initialization hooks to seed test data; neither copies the content of the primary database. On Zenifra, a preview does not create a database: it inherits the variables and, unless something changes, points to the same database as the primary project. That is simpler and adds no database cost, but it calls for the care described in the variables section.
When another option fits better: if you need a new, isolated database per pull request, created automatically, Render and Heroku do that today. If the project is a static or serverless frontend and the team already lives on Vercel, its Preview Deployments cover the case without a running server. Zenifra makes more sense when the application is a full HTTP server, billing needs to be in Brazilian reais, and the same console already hosts the application and the database.
| Platform | How the environment is created | Database and data | Removal | Billing |
|---|---|---|---|---|
| Zenifra | Automatic per PR from the same repository to the chosen branch (GitHub or Forgejo) or through the Action with an image | Inherits variables; does not create or copy a database; storage starts empty | PR closed, TTL (24 h default, up to 168 h), or project deletion | Project plan hourly price, in reais |
| Vercel | Push to a non-production branch, PR, or CLI without --prod | Own Preview variables, including per branch | Default 30-day retention for pre-production deployments (Hobby and Pro) | Retained deployments count toward Deployment Storage |
| Render | Preview Environments per PR (manual or automatic), requires Pro workspace or higher | Creates copies of services and datastores without data | PR merged or closed; optional expireAfterDays, no expiry by default | Same as other services, prorated by the second |
| Railway | PR environments enabled in Project Settings, Environments | Temporary environment per PR; Focused PR Environments for monorepos | PR merged or closed | Usage model: RAM US$ 10/GB-month, CPU US$ 20/vCPU-month |
| Heroku | Automatic or manual Review Apps; require Pipelines, GitHub, and app.json | Does not copy the database; seed with the postdeploy script | PR closed (automatic ones) and an option of 1, 2, 5, 14, or 30 days of inactivity | Dynos and add-ons like regular apps, prorated to the second |
Does a Preview copy the production database?
No. A preview does not create or copy a database: it inherits the primary project’s variables, so it may point to the same database, queue, or service. Review those values before testing so a change does not write to shared data.
To isolate tests, enable previews on a staging project whose variables point to a test database. Preview storage starts empty, so plan seed data when the application depends on it.
Do pull requests from forks get a Preview?
Not in the native flow. Only pull requests created in the project’s own repository and aimed at the chosen branch create a preview; forks and pull requests to other branches are left out, on both GitHub and Forgejo.
Pull requests already open before activation are not imported right away either: they start counting on the next relevant event, such as a new push.
How long does a Preview stay up?
Until the pull request closes or the expiration runs out, whichever comes first. The default is 24 hours, configurable between 1 and 168 hours, and every successful update renews the window.
Expired previews are removed automatically, including stopped ones, and compute and storage billing ends at the moment of removal. Deleting the primary project removes all of its previews at once.
What is the cheapest plan for Preview environments?
The smallest HTTP plan in the catalog is Static, at R$ 0.01 per hour, built for lightweight HTTP servers; for Node.js applications, the documentation recommends Basic, at R$ 0.05 per hour. The preview inherits the primary project’s plan, so there is no separate price.
A 24-hour preview costs R$ 0.24 on Static and R$ 1.20 on Basic. The primary project must be on a plan compatible with previews; if it is not, the API returns preview_plan_not_allowed.
How does the approved version reach production?
Through the flow configured on the primary project, not through the preview. There is no automatic promotion from Preview to the main application: with Automatic by branch, the merge deploys; with By Tag or By Release, the matching tag or release deploys.
After the merge, closing the pull request removes the native preview. Follow the production build in Build logs and validate the application on the public URL.