Projects & Builds
A project represents one web application. It is linked to a GitHub repo and has its own annotations, builds, members, and integrations. Each project gets a hosted preview URL.
CREATING A PROJECT
Click Projects → New Project to open the 5-step wizard. In workspace mode, members and above can submit project creation requests when approval policy is enabled.
Select Repository
GitHub repo + branch
Build Config
Auto-detected
Environment Vars
Encrypted at rest
Invite Team
Assign roles
Done!
Preview URL live
Select Repository
Connect your GitHub account, browse repos, choose a branch to track (default: main). If it's a monorepo, select a specific app path.
Build Configuration
BugDrop auto-detects your framework. Review and adjust install command, build command, and output directory.
Environment Variables
Add key/value variables your build needs. Values are encrypted at rest and hidden after save.
Invite Team
Invite developers, testers, clients, or guests to the project and assign their role.
Done!
BugDrop queues the initial build. Once complete, your preview URL is live and ready for review.
BUILD CONFIGURATION
- Branch
- Which branch is tracked and built
- Build Command
npm run build- Output Directory
dist or .next- Install Command
npm install- Pre-build Command
- Runs before the install step
- GitHub Webhook
- Auto-builds on every push (connects via GitHub App)
BUILD STATUSES
- Queued
- Waiting for a build slot to become available
- Building
- Clone, install, and build in progress
- Success
- Build completed — preview is live
- Failed
- Build failed — check the build logs
- Cancelled
- Manually cancelled before completion
BUILD LOG VIEWER
Go to Project → Builds → click any build. The log streams in real-time. Lines are colour-coded:
[system] ◉ Cloning repo: github.com/user/bugdrop-web (cyan)[stdout] > vite build (white)[stdout] ✓ Built in 14.2s[stderr] WARN missing peer: react-dom@^18.0.0 (amber)[system] ◉ Preview live at preview.bugdrop.io/prj_01HZ
Common build failures
1. Missing environment variables (Error: Cannot find module). 2. Package native binaries. 3. Output directory mismatch. Check the first stderr line for the root cause.
MONOREPO SUPPORT
BugDrop auto-detects Turborepo, Nx, and pnpm workspaces. Select exactly which app to build from the app picker:
BUILD FAQ
MANAGING MEMBERS
Go to Project → Members → Invite Member. Enter email and choose a role. They receive an invitation email with an acceptance link.
Owner
Account that created the project
Full access: settings, integrations, and member management
Developer
Engineers working on the codebase
View/manage annotations, apply fixes, access integrations, and vote on resolved/wont-fix approvals
Tester
QA specialists validating builds
View/manage annotations, update status directly (including resolved/wont-fix), and access integrations
Client
Stakeholders / end clients
Leave annotations, view their own reports — no access to code fixes
Guest
One-time reviewers (no account needed)
Limited annotation and comment access during a session
APPROVAL WORKFLOWS
Depending on workspace policy, project and integration actions may enter a review queue before they are applied.
- Project creation
- Members and above can submit. Owners and admins approve when project-create approval is enabled.
- Integration connect
- Managers, admins, and owners can approve integration connection requests when integration approval is enabled.
- Annotation status change
- Tester role can move annotations to resolved or wont_fix directly. Developer requests require more than 50% of project developers to approve, unless manager/admin/owner approves directly.
GUEST REVIEW LINKS
Clients can join without a BugDrop account. Generate a guest link inside an active review session.
No account required for guests
Guest annotations look identical to registered-user annotations in the dashboard. Guests receive an email when their annotation is resolved.