Skip to main content
Version: 1.38

Preview Environments

Preview Environments automatically create a live, production-like instance of your application for every pull request. This means faster feedback loops, reduced deployment risks, and the ability to test changes in a real environment before merging to main—no more "works on my machine" surprises.

Preview Environments

Okteto's Preview Environments are powered by Kubernetes and seamlessly integrate with your existing CI/CD workflows. Share live previews with designers, product managers, QA engineers, and stakeholders—anyone can test and provide feedback without needing to set up a development environment.

Why Preview Environments?​

Preview Environments transform how teams collaborate on code changes by providing instant, shareable environments for every pull request.

Accelerate Review Cycles

  • Share a live URL instead of screenshots or videos
  • Stakeholders can click through actual functionality
  • Get feedback from non-technical team members without complex setup
  • Reduce back-and-forth in PR comments

Catch Issues Early

  • Test integration with dependent services in production-like conditions
  • Identify configuration issues before they reach production
  • Run automated tests against real infrastructure
  • Validate database migrations and schema changes safely

Reduce Deployment Risk

  • Preview exactly what will be deployed to production
  • Test with production-like data and scale
  • Validate infrastructure changes alongside code changes
  • Ensure all services work together before merging

Improve Team Productivity

  • No more waiting for shared staging environments
  • Parallel development without conflicts
  • Automatic cleanup saves infrastructure costs
  • Focus on building features, not managing environments

How It Works​

Preview Environments in Okteto follow a simple, automated workflow:

  1. Open a Pull Request - When you create or update a PR in GitHub or GitLab, your CI/CD workflow triggers an Okteto Preview Environment automatically
  2. Automatic Deployment - Okteto deploys your application using your Okteto manifest, creating an isolated environment in response to the CI/CD trigger
  3. Share and Collaborate - Get a unique URL to share with your team for testing and feedback
  4. Automatic Updates - Push new commits, and your CI/CD workflow redeploys the Preview Environment with the latest changes
  5. Automatic Cleanup - When you close or merge the PR, your CI/CD workflow destroys the Preview Environment
tip

Preview Environments can run integration tests automatically, ensuring your changes work correctly before merging.

Getting Started​

Ready to add Preview Environments to your workflow? Choose your CI/CD platform:

  • GitHub Actions - Set up Preview Environments with GitHub
  • GitLab CI/CD - Integrate with GitLab pipelines
  • Bitbucket Pipelines (coming soon!)
  • Azure DevOps (coming soon!)

Prerequisites​

Preview Environments deploy the code in a pull request to Okteto. You can configure the way your code gets deployed using the Okteto manifest's deploy section.

Understanding Preview Scope​

Preview Environments can be configured with different visibility levels to match your team's workflow:

  • Global Scope (default): The Preview Environment is accessible to all members of your namespace. These previews are visible to the entire team and can be managed by users with appropriate permissions. Ideal for team collaboration and stakeholder reviews.

  • Personal Scope: The Preview Environment is only accessible to you and anyone you explicitly share it with. These previews are indicated with a user icon next to the preview name in the preview list. Perfect for testing experimental changes before sharing with the broader team.

info

Preview Environments use global scope by default. You can set the scope to personal when creating the Preview Environment if you need private access.

Working with Preview Environments​

Viewing Your Previews​

All Preview Environments are listed in the Okteto dashboard, where you can see their status, owner, and associated pull request. Click any preview name to view its details and access the live environment.

Filtering and Searching​

The Preview Environments list provides several filtering options to help you find specific previews:

  • Search - Search for previews by name using the search box
  • Repository - Filter by one or more repositories (searchable dropdown)
  • Status - Filter by preview status such as active, sleeping, or error states
  • Owner - Filter by the user who created the preview (searchable dropdown)
  • Updated - Filter by when the preview was last updated (last hour, 24 hours, 7 days, 30 days, or 90 days)

You can combine multiple filters to narrow down your search results.

Preview Information​

Each Preview Environment displays the following information:

  1. Name - The Preview Environment name. Click the name to view details. Previews with personal scope show a user icon next to the name.
  2. Repository - The repository hosting the code, with a link to view it in your source control provider
  3. Branch - The Git branch being deployed in this preview
  4. PR - A link to the associated pull request
  5. Owner - The user who created the Preview Environment
  6. Status - The current status of the preview (e.g., active, sleeping, deploying)
  7. Last Updated - When the preview was last modified

For detailed information on managing previews as an administrator (delete, wake, sleep, keep awake), see the Managing Preview Environments guide.