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.

For successful deploys, your pull/merge request comments include a link to the Deploy Preview by default. 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 deploy-preview-42--yoursitename.netlify.app. The web content of this URL is updated every time changes are pushed to the associated pull/merge request.

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.

# Limitations

  • On-demand Builders and server-side rendering. Collaboration tools are not available on sites using On-demand Builders or server-side rendering.
  • 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 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 60 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

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.

    # 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.