---
title: Preview Deployments
description: "Preview deployments allow you to test and review your application changes in an isolated environment before merging to production."
---

Preview deployments are a powerful feature specifically designed for applications with GitHub integration. This feature is disabled by default but can be easily enabled to enhance your development workflow.

<ImageZoom src="/assets/images/preview-deployments.png" width={800} height={630} alt='Preview deployments' className="rounded-lg" />

<Callout type="info">
We recommend not using preview deployments for public repositories, since external people can execute builds and deployments in your server.
</Callout>

## Configuration

By default, Dokploy generates dynamic domains using traefik.me domains, which are free and require no additional configuration. The default port is 3000, but you can adjust this based on your application's requirements. You can also limit the number of  preview deployments per application (default is 3).

### Custom Domains

If you prefer using a custom domain, you can configure it like this:

```
*.mydomain.com
```

Dokploy will generate domains following this pattern:

```
preview-${appName}-${uniqueId}.traefik.me
```

To make this work, you need to point your wildcard DNS record (*) to your server's IP address.

<Callout type="info">
**Hint:** If you need to reference the generated domain in the preview deployment's environment variables, you can do so utilising `${{DOKPLOY_DEPLOY_URL}}`. See [variables documentation](/docs/core/variables#service-level-variables) for more information.
</Callout>

## How It Works

Once enabled, preview deployments are automatically created whenever a pull request is opened against your target branch (configured in your provider settings).

For example:
- If your provider is configured to use the `main` branch
- And you create a pull request from `feature/new-feature` to `main`
- A preview deployment will be automatically created for the `feature/new-feature` branch

Note: Pull requests to branches other than your configured target branch will not trigger preview deployments.

### Filtering labels

If you only want pull requests with a specific label to create preview deployments, you can specify one or multiple in the preview settings.
Dokploy will check that at least one of the labels is present on the pull request. If you leave the settings field empty, Dokploy will create
preview deployments for all pull requests, regardless of labels.

### Monitoring Deployments

When you open a pull request, you can monitor the deployment progress in the preview deployments section:

<ImageZoom src="/assets/images/preview-deploy.png" width={800} height={630} alt='Preview deployments build' className="rounded-lg" />

In this section, you can:
- View the deployment status
- Access the preview URL once deployed
- Check build and deployment logs
- Monitor deployment updates
- Update domain configuration
- Manually rebuild preview deployments

### Automatic Updates

The preview deployment will automatically:
- Update with each new commit to the pull request
- Create a new build and deployment
- Clean up when the pull request is closed or merged

This continuous preview system allows teams to review and test changes in isolation before merging to production.

### Manual Rebuilds

You can manually rebuild a preview deployment without downloading new code from the repository. This is useful when you need to:

- Rebuild with updated environment variables or build settings
- Retry a failed build without making code changes
- Apply configuration changes that require a rebuild

To rebuild a preview deployment, click the **Rebuild** button (hammer icon) next to the deployment and confirm the action. The rebuild will use the existing code and only re-run the build process.

<Callout type="info">
  If you have security or redirects created in your application, it will inherit the same configuration for the preview deployment.
</Callout>
