Connect the repository
Select the account or workspace that will own the project
Open Settings → Version Control and connect GitHub, GitLab, or Bitbucket using the provider shown for your repository.
Authorize the correct account and grant repository access
For a private repository, ensure the provider connection includes that repository; being able to view it in your own browser is not enough.
Open Projects → New Project, choose the connected provider, select the repository and branch, then review the detected settings.
If access requires approval, submit the request
Track it in your work/approval queue; an authorized owner or workspace manager must approve before the requested operation takes effect. Read a rejection reason and correct the request before resubmitting.
Configure the application build
Create the project, open its build logs, and verify that the preview loads a real application route. For new configuration or changed variables, make a new build; do not assume an old preview has picked up new settings.
| Setting | What to enter |
|---|---|
| Root directory | The app directory relative to the repository root. Use the actual package location for a monorepo. |
| Install command | The package manager command matching the app's lockfile and workspace layout. |
| Build command | The app's production build command. Check the framework's required version and adapter. |
| Static output | The directory your command actually creates, such as dist. Do not use .next as a generic static folder. |
| SSR configuration | The supported server/framework output and adapter selected for your app. A successful static build does not prove SSR runtime compatibility. |
| Environment variables | The build/runtime values required by the app; save them before the build. See Environment Variables. |
Choose review access
Use the project's Team controls to invite a developer, tester, or client and choose the role deliberately. Workspace People manages workspace membership; it is not the same role list.
Client and guest visibility is based on public annotations in their permitted project/review context, not an author-only rule. They may see other public reports. Internal annotations and staff-only comments are restricted. See Team & Roles before sharing confidential issue details.
Project owners manage project configuration and backend setup. Workspace authority can affect effective access; project ownership is not simply a guarantee that whoever clicked Create can bypass all workspace rules.
Repository or preview setup failed
For a missing repository, confirm the selected provider account and granted repositories, then reconnect or refresh. For Cannot find module, check installation, dependency declarations, monorepo root, and build paths. For a missing-variable error, check the required variable name and where the framework reads it.
Inspect the first actionable error in the failed build, not necessarily its first stderr line. Use Builds & Previews to retry after correcting the cause.