# Preview Deployments (/docs/guides/preview-deployments)



Every pull request can get its own live environment with a unique URL, so you can test changes before merging.

## How It Works [#how-it-works]

1. You open a pull request on GitHub
2. Rock8Cloud builds and deploys a preview environment
3. A preview URL is available (e.g., `https://pr-42--your-service.rock8cloud.app`). Apps still on the old `apps.rock8.cloud` address keep the old preview shape (`pr-42-your-service-your-org.apps.rock8.cloud`)
4. Push more commits → the preview updates automatically
5. Close or merge the PR → the preview is cleaned up, or delete it yourself at any time

## Configuration [#configuration]

The **Preview Deployments** workflow is enabled by default. To adjust:

1. Open the service **Workflows** tab
2. Find the **Preview Deployments** workflow
3. Configure source branch patterns (defaults to `feat/*`)
4. Configure target branch if needed (defaults to the service's default branch)

See [Workflows](/docs/guides/workflows) for the full configuration reference.

## Requesting a preview manually [#requesting-a-preview-manually]

You can request a preview directly from an open pull request. Add a comment using the GitHub App's account name and the service name:

```text
@github-app preview frontend
```

Replace `github-app` with the account name of the Rock8Cloud GitHub App installed for your repository, and replace `frontend` with the name of your repo-backed service.

The command uses the pull request's current commit and creates or redeploys that PR's preview environment. It works even when the **Preview Deployments** workflow is disabled or its branch filters do not match. Only the repository owner, organization members, and repository collaborators can run preview commands.

If the organization has no available pod capacity, the request waits in a parked environment and starts automatically when capacity is available. If the service is sleeping, wake it and the pending preview resumes. Repeating a command for the same pull request commit does not create another deployment.

A running preview keeps tracking its pull request: every new commit pushed to the PR rebuilds it. The only exception is a pull request that an enabled **Preview Deployments** workflow already deploys, since that workflow handles the rebuild. This holds for previews created by the command and for previews created by the workflow.

## Environment Variables [#environment-variables]

Preview deployments use the **same environment variables** as your stable deployment. If you need isolated databases or API keys for previews, create a separate project.

## Cleanup [#cleanup]

Previews are automatically removed when the pull request is closed or merged. No manual cleanup needed.

### Deleting a preview manually [#deleting-a-preview-manually]

You can remove a preview before its pull request is closed, for example to free up capacity:

1. Select the preview environment (**PR #123** in the service sidebar)
2. Open the **Overview** tab
3. Open the actions menu in the header bar and choose **Delete environment**

The preview stops running and its URL goes away. The pull request itself is untouched. To recreate the preview:

* Push another commit when the **Preview Deployments** workflow is enabled and matches the branch.
* Otherwise run the `@<app> preview <service>` command again.

## Troubleshooting [#troubleshooting]

| Problem                                     | Solution                                                      |
| ------------------------------------------- | ------------------------------------------------------------- |
| No preview created                          | Check the workflow is enabled and branch patterns match       |
| Preview waiting for pod capacity            | It starts automatically when capacity is available            |
| Preview waiting because service is sleeping | Wake the service to resume the pending preview                |
| Preview not updating                        | Verify new commits triggered a `synchronize` event            |
| Preview not removed                         | Delete it manually from **Overview** → **Delete environment** |

## Related [#related]

* [Workflows](/docs/guides/workflows)
* [How Rock8Cloud Works](/docs/how-deployments-work)
* [Environment Variables](/docs/guides/environment-variables)