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 pull requests and 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.

You can control who can access your site’s Deploy Previews by requiring a password to visit your Deploy Preview. Learn more at our password-protection docs.

# 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 deploy-preview-42--yoursitename.netlify.app.

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: 1234abcd12acde000111cdef--yoursitename.netlify.app. 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.

# 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 a pull or 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.

# Connect to a Git provider

When you connect to a Git provider from the Netlify Drawer, your Git provider identity is connected to your Netlify user, which creates a more integrated experience sharing feedback in pull/merge requests or in issues/work items.

Within the Netlify Drawer, you can connect to the following Git providers:

Once you connect to your Git provider user account, comments you write in the Netlify drawer will be synced to the pull/merge request and authored by your Git provider user.

Connecting to a Git provider also allows you to open issues in your Git provider directly from the Netlify Drawer.

If comments appear as authored by the wrong user, check out how to adjust the comment author.

# Send Deploy Preview feedback to productivity tools

In addition to Git providers, you can send feedback about a Deploy Preview to supported productivity tools through the Netlify UI.

Productivity tools that integrate with Deploy Preview feedback comments:

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, or in a pull/merge request. 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 pull request or 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 repository resets environment variables

If you are using the classic environment variables experience, relinking your repository will remove your environment variables automatically. We recommend copying the environment variables you need before relinking your GitLab repository.

  1. On Netlify, if you are using the classic environment variables experience and have any environment variables set in the Netlify UI, 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, re-create them with the Netlify 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 app.netlify.com and netlify-cdp-loader.netlify.app to the allow list in the _headers or netlify.toml file. For example:

/* 
  Content-Security-Policy: child-src 'self' app.netlify.com; script-src 'self' app.netlify.com netlify-cdp-loader.netlify.app;
[[headers]]
  for = "/*"
  [headers.values]
    Content-Security-Policy = "child-src 'self' app.netlify.com; script-src 'self' app.netlify.com netlify-cdp-loader.netlify.app;"

# 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 [*.]netlify.app and select to include third-party cookies on the site.

# Comment author appears as a different user

If the person giving feedback doesn’t have a Git provider account or doesn’t connect to a Git provider through the Netlify Drawer, then that person’s feedback comments may appear in a pull/merge request as a different default Netlify user.

By default, if the comment author doesn’t have their Git provider account and Netlify user synced, then their comments are attributed to the Netlify user who linked the site to the repository.

If you’re a comment author with a Git provider account and you want your review comments synced with your Git provider ID, then you can connect to your Git provider through the Netlify Drawer by selecting the Integrations tab.

As an alternative, you can set up a generic user account on the Git provider with the name “Netlify”. Once set up, all comments from people who do not have a Git provider account, or have not authenticated through the Git provider, are attributed to this generic “Netlify” user on merge/pull requests.

Once set up, all comments from people who do not have a Git provider account, or have not authenticated through the Git provider, are attributed to this generic “Netlify” user on merge/pull requests.

# Set up a “Netlify” user for review comments in Azure DevOps

You can create a generic user named “Netlify” for everyone who has not authenticated to Azure DevOps, or who does not have sufficient permissions to comment on the pull request in Azure DevOps.

Once a generic user is set up, anyone who leaves feedback without authenticating to the Git provider will have their feedback attributed to the generic “Netlify” user.

To set this up, an administrator on Azure DevOps can take these steps:

  1. In Azure DevOps, create a new role with at least a Basic role or higher permissions.
  2. Confirm the user and log into Azure DevOps with that account.
  3. Edit the Azure DevOps 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 this feedback with Netlify’s collaboration tools.
  4. Generate a personal access token with a Code: read & write scope, and copy the token to your clipboard.
  5. In a Deploy Preview for a site connected to an Azure DevOps repo, sign in through the Netlify Drawer.
  6. In the Netlify Drawer, select the gear icon to open Deploy settings. Paste in the token from Azure DevOps, and select Set Azure DevOps token.
# Set up a “Netlify” user for review comments in GitLab

To set up a “Netlify” user to appear in review comments from people who have not authenticated with GitLab, 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 people 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.