The Definitive Guide to Preview Environments

Preview Environments aka Ephemeral Environments are created on-demand for testing a specific git branch before it's merged. Preview Environments— unlike persistent Staging or Production Environments—are intended to be short-lived and single-purpose, existing only as long as they are needed to test a specific feature or bug fix. Preview Environments often share the same lifecycle as the event that triggered it, typically a pull request/merge request. That is, they're created when a PR is opened and destroyed when the PR is merged or closed; alternatively, they may also be set to timeout after several hours.

‍

‍Preview Environments help software teams increase their development velocity by reducing the time it takes to acceptance test new features. They enable faster reviews, rapid feedback, and iterative cycles. They enable teams to standardize a best practice for code review, and they ultimately reduce the workload on maintainers and team leaders who are responsible for dozens of pull requests every month.  

‍

Preview Environments empower teams to shift their testing process to “pre-merge” where it’s significantly easier to find bugs, isolate responsibility, and make the appropriate changes. You can think of Preview Environments as a quality gate that allows features to be thoroughly tested and iterated upon in isolation. The net effect is feature parallelization or what is sometimes called “shifting left”. This is why we say, “Don’t merge until you preview” or “Keep dirty code out of main.”

‍

Preview Environments fill the gap between local testing and your Staging environment or Production Environment. They are designed to test individual features or topic branches in a production-like environment that includes a full-stack of services. They have a purpose-driven or ephemeral life-cycle which means that they exist only as long as they are needed for review.  Configure it to create efficiency when you deploy code changes.

‍

In practice, Preview Environments are most often created and deleted in response to a pull request (PR) or merge request (MR) trigger.

‍

A Preview Environment is often synonymous with pull requests (PR) environments, on-demand environments or ephemeral environments, with implementation details varying depending on the use case. When a new pull request comment is created a Preview Environment is also created.  When the PR is updated the Environment is updated. And when the PR is merged or closed the Environment is deleted.

‍

With preview environments, you give your team the capability to have as many test environments as you need, when you need them, and only for as long as you need them. They primarily benefit maintainers and team leads who are overall responsible for speed of delivery and code quality but they are also a great cross-functional team tool because they benefit developers, testers, product team, and other key stakeholders.

‍

As platforms like Netlify and Vercel have popularized previews for frontends and visual changes, the newly emerging preview environment is a natural complement for backends, databases, APIs, CLIs, Binaries, and, in general, any microservices application.  Many consider the capability to be a “game changer” and the “holy-grail” of DevOps.

‍

‍Indicators that Preview Environments are right for your team

• How quickly you ship is existential for your business
• Releases are held up by buggy commits in a trunk branch
• It takes a long time to merge new PRs/MRs
• Your team lead spends a lot of their time pulling a code branch or branches to test or debug on their local machine
• Your engineering team experiences “Code Freezes” in the development cycle or development process.
• Your team has more than or will have more than 4 developers using a shared test environment
• Your team has frontend previews but no backend equivalent
• Your team members are delayed by automated test queues
• You want to improve collaboration between your cross-functional team of developers, testers, product, and other key stakeholders
• You want to demo a new feature with a POC environment but have no easy way to provision one
• You have to contact an engineer on the Ops or DevOps teams to get an environment

‍Common benefits of a Preview Environment Capability

Below are common benefits when preview environments become an integral part of your development process.

‍

5x Your Release Frequency

Preview Environments enable fast cycles for every Pull Request - this accelerates how quickly you can review, provide feedback, and complete acceptance testing.

Feature fratricide and co-dependency is a major problem as teams try to grow and scale against a shared environment. Preview Environments enable you to decouple each Developers contributions from each other so as soon as a new feature is ready it can be released - you don't have to worry about bugs being introduced that are unrelated to any specific feature.

‍

Unburden your team lead or open-source maintainer

Development Team leads and open-source maintainers bear a huge amount of responsibility. To mitigate merge risks they will often want to see a running version of a Pull Request before they approve it.

Without Preview Environments this means pulling down the branch and running it in their local dev environment. This, of course, can be time consuming—multiply it by the number of developers on the team, and this becomes their whole job.  More importantly each maintainer may do this with a different environment set-up which makes standardization impossible and makes for an inefficient code review and deployment cycle.  If your application has a number of dependencies the challenge here is multiplied.

‍

Catch bugs before merging

Identifying bugs prior to merging will save time and headaches for your Development Team lead. If you merge buggy code to a trunk branch, you’ve made an unforced error.

You won’t be able to cut a new release to production without 1.) Reverting your changes (=RISKY) or 2.) Waiting for the bugs to be fixed. And, of course, if you’ve broken a shared environment all testing will grind to a halt.

‍

With a Preview Environment you can review code in a standardized, holistic way which drastically improves the odds of catching bugs early. You can use Preview Environments to run automated tests or conduct manual exploratory testing—either way your team lead will thank you for keeping dirty code out of a trunk branch.  

‍

‍That’s not what I had envisioned

Ensuring continuity between what is designed and what is implemented is a ubiquitous organizational challenge. Preview Environments solve this by enabling your team to bring in all the key stakeholders early in the process.

Would you rather find out the product owner doesn’t like how something was implemented right after you code it, or a week later when they see it for the first time? Create end to end visibility across your entire organization.

‍

Standardizing how you operate

Preview Environments enforce a best practices process that can be replicated across all of your teams.

For example how one team lead pulls code to run in their local environment will not necessarily match how another does it. Preview Environments as part of your Continuous Integration represent a best practice that all teams can follow.

‍

Continuous Testing

Continuous is a term that represents something every team strives for, hence continuous integration, continuous delivery and continuous deployment. Continuous testing is no different. Finding issues earlier in the Software Development Life-cycle benefits everyone. Preview Environments are designed to be rapidly created and updated to enable continuous testing - either manual testing, automated testing, or ideally both.

‍

Circumvent the automated test queue

As automated testing matures for any project, the queue against a single or limited number of environments becomes its own bottleneck.

This “queuing effect”—waiting up to several hours for tests to run—will only grow over time and continue to slow your team down. A Preview Environment enables faster feedback loops. Previewing can be done in parallel so that a single buggy commit does not hold up the entire forward progress of all the working commits.

‍

Reviewing test environment models

Unlike traditional QA or staging environments which often become polluted over time from data accumulation and conflicting commits, Preview Environments are ephemeral and intended to test a single topic branch. Once they reach the end of their useful life, their resources—including their data—are destroyed. This design isolates developer responsibility and simplifies root cause analysis since each environment is associated with a single feature or bug fix. The dynamic nature of Preview Environments, however, presents some unique challenges that are not present in persistent test environments.

‍

‍

‍

‍

‍

Common challenges of Preview Environments

‍Test Data

Reviewing against a relevant set of data is critical to the process for many applications.  For Preview Environments to be effective in this scenario the database needs to be seeded with a relevant set of data. To learn more about how to solve this problem check our section on Data for Preview Environments.

‍

Negotiating managed services

If you are relying on various managed cloud-based services you can "mock" those services in your Preview Environments. Common services like Postgres, MySQL, Redis can easily be run as containers and if you need something AWS specific like Lamda or S3, you can pull these "mock" containers from Localstack's public Docker Hub repository.

‍

If you have a stateful service that cannot be represented as a container or a virtualized service, then you probably want to connect to it read-only, or not connect at all. If this is a sticking point for your particular application, you will want to look for an infrastructure-as-code based-solution that can help you create/delete instances of your managed service for your Preview Environment.

‍

Dealing with serverless

Connecting environments to serverless platforms like AWS Lambda can be a point of friction. Fortunately many of these can be containerized as an effective substitute to run in your Preview Environments.

‍

Dynamic URLs

Often many services will depend on calls to a static URL (i.e. qa.acme.com). Preview Environments have a dynamic URL which means you may have to do some work to ensure that your team can dynamically interact with key dependencies.

If dynamic URLs follow a predictable format as they do on Uffizzi, that can drastically simplify connecting to other services in a predictable and dynamic way.

At Uffizzi we are actively working on a solution to enable dynamic updating of backlinks to key services like OAuth and we look forward to posting about that in our Preview Environments Guide.

‍

Getting started with Preview Environments

For certain teams and applications it may make sense to create your own preview tool, but we highly recommend avoiding this route if possible.

It’s extremely costly for two, three, or more engineers to set up, build, and maintain a custom preview environment tool—especially since there’s handful of solutions on the market that will likely fit your needs and which are constantly improving.

For teams who want Preview Environments on their own infrastructure, open-source Uffizzi is the only self-hosted solution of its kind. And for teams that want Environments as a Service, Uffizzi Cloud provides the fastest way and most low maintenance way for teams to get started.

Uffizzi integrates with any version control system, CI-provider, and container registry. Define your applications with Docker Compose, then use one of our GitHub Actions workflows or GitLab jobs for easy integration.

You can set up a working example in ~1 minute using our quickstart repo.  It can be configured and deployed from GitHub and includes an automatic free account configuration on Uffizzi.

‍

The results of implementing Preview Environments

• From 1 release per week, to 1 release per day
• 64% increase in release frequency
• 36% increase in issues completed
• 20% reduction in issues per release

What are Engineers' perceptions of Preview Environments?

80% say that Preview Environments are either Valuable (45%) or Extremely Valuable (35%).

If you don't have an existing CI solution, Uffizzi CI can build your application from source and store your container images for you. Please note that your source code must be stored in a GitHub repository to use Uffizzi CI.

This demo deploys a To-Do app frontend on Netlify and backend on Uffizzi

This demo deploys the FoodAdvisor frontend on Vercel and API (Strapi) on Uffizzi.

‍