Preview deployments - Mintlify

Create preview deployments

Create preview deployments automatically through pull requests or manually from your dashboard.

Automatic previews

Automatic previews are only created for pull requests targeting your deployment branch.

When you create a pull request, the Mintlify bot automatically adds a link to view the preview deployment in your pull request. The preview updates each time you push new commits to the branch.

Fork pull requests

Pull requests opened from a fork do not generate preview deployments. The Mintlify GitHub App can only generate previews for repositories where you install it, so it cannot read a fork or build a preview against it. A maintainer with write access to the main repository can preview changes from a fork. They can push the forked contributor’s branch to a branch in the main repository or merge the fork into an integration branch. The GitHub App can then build a preview for a pull request opened from that branch.

Manual previews

You can manually create a preview for any branch.

1. Go to the Activity page in your dashboard.
2. Click the Previews tab.
3. Click Create custom preview.
4. Enter the name of the branch you want to preview.
5. Click Create preview.

API

You can also create preview deployments programmatically using the Trigger preview deployment API endpoint. This is useful for integrating preview creation into continuous integration and continuous delivery (CI/CD) pipelines or custom tooling.

Redeploy a preview

Redeploy a preview to refresh content or retry after a failed deployment.

1. Go to the Activity page in your dashboard.
2. Click the Previews tab.
3. Click the preview you want to redeploy.
4. Click Redeploy.

Preview widget

The preview widget appears on preview deployments to help you navigate and review updated pages. The widget is a floating button in the bottom-right corner of your preview deployment.

1. Click the widget to show all added, modified, or removed files in the preview.
2. Click a file to view the changes on the corresponding page.
3. Use the search bar to filter the list of changed files.
4. Hover over a file and click the Open in editor icon to edit the file directly in the web editor.

The widget only appears on preview deployments, not on your live site or local previews.

Restrict access to preview deployments

Restricting access to preview deployments requires an Enterprise plan.

By default, preview deployments are publicly accessible to anyone with the URL. You can restrict access by requiring organization authentication for all previews or by password-protecting individual previews. If your site requires authentication to access, Mintlify automatically enables preview authentication and you cannot disable it. Reviewers sign in to previews with the same authentication method your site uses.

Require organization authentication

Restrict preview access to authenticated members of your Mintlify organization.

1. Go to the Previews section of the Add-ons page in your dashboard.
2. Click the Preview authentication toggle to enable or disable preview authentication.

Password-protect an individual preview

Password-protect a specific preview to share it with external reviewers without adding them to your Mintlify organization. This option is available when you create a manual preview from your dashboard. The Make private toggle does not appear if your plan does not include preview authentication or if your site requires authentication.

1. Go to the Activity page in your dashboard.

2. Click the Previews tab.

3. Click Create custom preview.

4. Enter the name of the branch you want to preview.

5. Toggle Make private on and enter a password. Passwords must be at least 8 characters.

6. Click Create preview.

Preview lifetime

Preview deployments stay live as long as their source branch exists in your repository and continue to receive updates on every push.

• Automatic previews: The preview for a pull request remains available while the pull request is open and after it’s merged or closed, as long as the source branch still exists. When you delete the branch, the next dashboard sync removes the preview.
• Manual previews: Manual previews stay live until you delete them. Redeploying a manual preview refreshes its content against the latest commit on the specified branch.
• Delete a preview: On the Activity page of your dashboard, click the Previews tab, open the preview, and click Delete to remove it immediately.

Preview URLs are unique per branch. If you delete a preview and later recreate one for the same branch, Mintlify may issue a new URL. Mintlify generates preview URLs automatically. The subdomain and domain are not configurable, and custom domains only apply to your production deployment.

Troubleshooting preview deployments

If your preview deployment fails, try these troubleshooting steps.

• View the build logs: On the Activity page of your dashboard, click the Previews tab and click the failed preview. The deployment logs show errors that caused failures.
• Check your configuration:
  • Missing docs.json at the configured content root. If your docs.json is in a subdirectory, confirm the docs.json is in a subdirectory setting points to the correct path.
  • Invalid docs.json syntax (for example, an empty file or a stray trailing comma that breaks JSON parsing).
  • Schema errors in docs.json such as an invalid theme, malformed navigation, or unresolved $ref values.
  • Missing or incorrect file paths referenced in your navigation.
  • Invalid frontmatter in MDX files.
  • Broken image links or missing image files.
• Validate locally: Run mint dev and mint validate locally to catch configuration and build errors before pushing to the repository.
• Check recent changes: Review the most recent commits in your branch to identify what changes caused the build to fail.