Deploy Previews

Deploy Previews allow you and your team to experience changes to any part of your site without having to publish them to production.

Netlify builds Deploy Previews by default for GitHub pull requests and GitLab merge requests. You can control whether or not Deploy Previews are generated for pull/merge requests. For more information, visit the Deploy Preview controls docs.

While Netlify creates a Deploy Preview for your pull/merge request, the Deploy Preview status updates to reflect the progression. If the deploy is successful, Netlify adds a comment to your pull/merge request with a link to the Deploy Preview. You can add, remove, or edit these notifications. Visit the deploy notifications doc for more information.

# Deploy Preview URLs

Deploy Previews work by deploying pull/merge requests to a unique URL different from the one your production site uses. This URL has the prefix deploy-preview followed by the identifier number of the pull request or merge request. For example, a Deploy Preview for pull/merge request #42 will deploy to

While the initial deploy for your pull/merge request is pending, this URL will result in a Not Found error. For subsequent changes, the web content of the Deploy Preview URL will update as changes are pushed to the pull/merge request and successfully deployed.

You can share this URL with your team to collaborate and gather feedback.

Every deploy also has a permalink that starts with the deploy ID number. For example: The contents of this URL never change, even after you redeploy your site.

# Collaborative Deploy Previews

With collaborative Deploy Previews, you and your team can add, review, and manage feedback about site changes right from your site. You can leave comments, take screenshots and video, and test responsiveness on a mobile device.

You can access collaboration tools from the Netlify Drawer.

Netlify Drawer icon.

# Requirements and limitations

Keep the following considerations in mind when working with collaborative Deploy Previews.

# Requirements

  • Deploy Preview URLs. Collaboration tools are only available on Deploy Previews accessed through their deploy-preview prefixed URLs.
  • GitHub App permissions. If you’re using GitHub, verify that the Netlify GitHub App is installed with the necessary permissions.
  • Valid HTML. Your site must have valid HTML output with opening and closing body tags.
  • Team access. Stakeholders must be signed into Netlify and granted access to a team to use the collaboration tools. To request access to collaborate, select the Team Members tab and select Request to join team.

For site pages with server-side rendering (SSR) or Incremental Static Regeneration (ISR), your function must also set these response headers:

  • The function generating the page requires Content-Type with text/html.
  • If the function response is compressed, Content-Encoding is required in the function response. The supported compression algorithms are brotli (br) and gzip (gzip).

For examples of a server-side rendering site that works with Collaborative Deploy Previews, check out our official Next.js template repository.

# Limitations

  • Bitbucket. Collaboration tools are currently not available on Bitbucket deploys.
  • Azure DevOps. Collaboration tools are currently not available on Azure DevOps deploys. Azure DevOps is currently in the beta stage.

# Give feedback

The Netlify Drawer provides access to a number of collaboration tools that team members and approved Reviewers can use to leave feedback about a Deploy Preview. Select Deploy Preview to access the full contents of the drawer.

# Leave comments

Team members and approved Reviewers can leave comments on the Deploy Preview that are synced and mirrored on the GitHub pull request or GitLab merge request. From the open drawer, select the Activity tab to start writing a comment.

If you are a pending Reviewer, your submitted comments will remain hidden until a team Owner or Collaborator approves you.

# Send feedback to third-party services

You can send feedback about a Deploy Preview to a number of productivity tools by connecting your Netlify user account to your user account for the tool:

To get started, from the open Netlify Drawer go to the Integrations tab and select Connect for the third-party service you want to use.

Netlify Drawer Integrations tab.

Once your Netlify user account is connected to a third-party service, you can submit feedback to the service directly from the Deploy Preview by selecting New issue.

# Take screenshots and record screen

You can take a screenshot or screen recording and use it in feedback in the pull/merge request or third-party integration.

To add a screenshot, select Screenshot. You can edit and annotate your screenshot before using it in feedback.

To record a screen interaction without audio, select Record. You can use the screen recording in your feedback as a GIF. To include audio or webcam footage as well as a screen interaction, record feedback with Loom.

You can also drag and drop image and video files directly onto the Activity tab text area to include them in a comment using Markdown syntax.

# Record feedback with Loom

You can record and share feedback directly from a collaborative Deploy Preview using Loom. Unlike the Record option in the Netlify Drawer, Loom offers a selection of screen capture, audio, webcam video, or all three. The collaborative Deploy Preview Loom integration currently works with Google Chrome and Microsoft Edge.

  1. To get started, from the open Netlify Drawer go to the Integrations tab and select the toggle to enable Loom for your Deploy Preview feedback. If prompted to enable third-party cookies, check out our Loom troubleshooting section.
  2. Select Loom to launch the Loom settings options, make your setting selections, and then Start recording.

You can use the Loom recording in a new comment or copy a link to share it in your feedback.

Loom provides up to five five-minute recordings from a collaborative Deploy Preview for free without a Loom account. If you’re signed into a Loom account, recording limits vary according to your Loom plan.

# Get feedback

The Netlify Drawer also provides tools for team Owners and Collaborators to request feedback about a Deploy Preview.

# Invite contributors

You can select Add members to invite users to join your team, including an unlimited number of free Reviewers.

For more information on team member permissions, check the team roles documentation.

# Set entry path

The entry path is the page visitors will land on when they access your Deploy Preview using links on the Deploys page, deploy details page, in GitHub, or in GitLab. You can set an entry path in the following ways:

  • Enter the path in the Settings tab of the Netlify Drawer.
  • Tag @netlify /path/to/page in the initial description of your GitHub pull request or GitLab merge request.

When writing a value for the entry path, it must be relative and start with /.

# Test and troubleshoot with collaboration tools

The Netlify Drawer provides access to tools that team Owners, Collaborators, and Reviewers can use to test and troubleshoot specific site deploys.

# Monitor logs

Owners and Collaborators can access the deploy log and serverless function logs in the Netlify Drawer to help with monitoring and troubleshooting a specific deploy.

To find details about the deploy, open the Deploy logs tab of the Netlify Drawer. Visit our deploy log docs for more information.

You can access function logs by opening the Function logs tab in the Netlify Drawer and selecting a function to check out its latest log contents for the current session. Visit our function logs docs for more information.

# Check responsiveness and site performance

You can open your Deploy Preview on a mobile device to check your site’s performance and test responsiveness. Select Scan then scan the QR code with a device to open the page.

# Access browser details and replicate in BrowserStack

When someone shares feedback through a collaborative Deploy Preview, you can access metadata about the browser the comment author used. You can also replicate their browser environment for testing and QA through a built-in integration with BrowserStack.

In collaborative Deploy Preview feedback, find the browser information (usually near the bottom of the feedback) and select Open in BrowserStack to launch a BrowserStack instance that matches the author of the comment’s browser, browser version, viewport size, and operating system.

The BrowserStack service provides a free 30 minute total usage allotment for users who sign up from Netlify. An option to upgrade is available in BrowserStack once the allotment is finished.

# Troubleshooting collaborative Deploy Previews

This section provides troubleshooting tips for using and accessing collaborative Deploy Previews. Make sure you have reviewed the requirements and limitations for collaborative Deploy Previews before you begin.

If you have additional concerns that aren’t answered here, you can visit our Forums to ask questions and find more information.

# Netlify Drawer is missing for a site connected to GitLab

If the Netlify Drawer is missing on your Deploy Preview or has a “Something went wrong” error, this error is likely caused by a GitLab 15.0 update that no longer supports OAuth tokens without an expiration date.

Use Git Gateway or deploy notifications?

Your connection to GitLab for these features may also be impacted by the GitLab 15.0 update. Learn more about how to resolve these issues for Git Gateway or deploy notifications.

To get your collaborative Deploy Preview drawer working again, you’ll need to reauthenticate by relinking your GitLab repository to your site.

Relinking a GitLab repo resets environment variables

Once you relink your GitLab repository, environment variables are automatically removed. We recommend copying the environment variables you need before relinking your GitLab repository.

  1. On Netlify, if you have any environment variables set in Netlify’s UI that you’d like to keep for your site, copy and store them in a secure place.
  2. Go to Site settings > Build & deploy > Continuous deployment > Repository > Manage repository > Link to a different repository, and link your existing GitLab repository to your site on Netlify.
  3. If you copied environment variables, add them back to Netlify’s UI.

# Netlify Drawer is missing

If you can’t find the Netlify Drawer on your Deploy Preview, verify that the Netlify Drawer is enabled for your site. You can do this by going to your site in the Netlify UI and selecting Site settings > Build & deploy > Continuous Deployment > Deploy Previews.

The Netlify Drawer also might not appear if your site’s custom headers include the following Content Security Policy (CSP) directives:

  • default-src
  • script-src
  • frame-src
  • child-src

To address this issue, add and to the allow list in the _headers or netlify.toml file. For example:

  Content-Security-Policy: child-src 'self'; script-src 'self';
  for = "/*"
    Content-Security-Policy = "child-src 'self'; script-src 'self';"

# Netlify Drawer blocks content

If the Netlify Drawer is blocking important UI elements, you can minimize or dismiss the drawer for the duration of the session.

# Loom requires third-party cookies

You may be prompted to enable third-party cookies while trying to enable the Loom integration for collaborative Deploy Previews.

On Google Chrome, you can allow cookies for a specific site. To add the Netlify app to Sites that can always use cookies, enter [*.] and select to include third-party cookies on the site.

# Reviewer comments appear as a different GitLab user

If a Reviewer authenticates with GitLab, comments they add through collaboration tools in a Deploy Preview are mirrored in a merge request using their GitLab profile. If a Reviewer doesn’t authenticate with GitLab or doesn’t have a GitLab account, comments mirrored in a merge request appear under the profile of the GitLab user who configured the site on Netlify. These mirrored comments start with A reviewer left a comment.

To change the GitLab user for unauthenticated comments on merge requests, a GitLab project Owner or Maintainer can take these steps:

  1. In GitLab, invite a new user with a role of Reporter or above to your project. The email address for this user must be one you have access to.

  2. Confirm the user and log into GitLab with that account.

  3. Edit the GitLab profile of the user to change the Full name and Public avatar. We recommend naming the user Netlify and using the Netlify logo as the avatar to help associate unauthenticated comments with Netlify.

  4. Generate a personal access token with an api scope, and copy the token to your clipboard.

  5. In a Deploy Preview from one of your GitLab sites, open the Deploy settings tab in the Netlify Drawer. Paste in the token from GitLab, and select Save.

    Comments left by Reviewers who have not authenticated with GitLab should now be associated with the Netlify user on your project.

# Preview changes without the Netlify Drawer

To opt out of loading the Netlify Drawer on a site’s Deploy Previews, go to Site settings > Build & deploy > Continuous Deployment > Deploy Previews, select Edit settings, and disable the Netlify Drawer.

You can also open a branch deploy or deploy permalink if you need to preview a deploy but don’t want to access any of the collaboration features. Both links are available in the Netlify Drawer under Settings. The branch deploy link is also available on your site’s Deploys page in the Netlify UI, while the deploy permalink is available on the deploy details page.