feat(preview): add collaborator permission requirement for preview deployments

- Introduced a new boolean field `previewRequireCollaboratorPermissions` in the application schema to enforce permission checks for preview deployments.
- Updated the UI to include a toggle for this setting in the preview deployment settings.
- Enhanced GitHub deployment handler to validate PR authors against the required permissions, blocking unauthorized deployments and providing security notifications.
- Added SQL migration to update the database schema accordingly.

apps/dokploy/components/dashboard/application/preview-deployments/show-preview-settings.tsx

@@ -46,6 +46,7 @@ const schema = z
 		previewPath: z.string(),
 		previewCertificateType: z.enum(["letsencrypt", "none", "custom"]),
 		previewCustomCertResolver: z.string().optional(),
+		previewRequireCollaboratorPermissions: z.boolean(),
 	})
 	.superRefine((input, ctx) => {
 		if (
@@ -83,6 +84,7 @@ export const ShowPreviewSettings = ({ applicationId }: Props) => {
 			previewHttps: false,
 			previewPath: "/",
 			previewCertificateType: "none",
+			previewRequireCollaboratorPermissions: true,
 		},
 		resolver: zodResolver(schema),
 	});
@@ -105,6 +107,8 @@ export const ShowPreviewSettings = ({ applicationId }: Props) => {
 				previewPath: data.previewPath || "/",
 				previewCertificateType: data.previewCertificateType || "none",
 				previewCustomCertResolver: data.previewCustomCertResolver || "",
+				previewRequireCollaboratorPermissions:
+					data.previewRequireCollaboratorPermissions || true,
 			});
 		}
 	}, [data]);
@@ -121,6 +125,8 @@ export const ShowPreviewSettings = ({ applicationId }: Props) => {
 			previewPath: formData.previewPath,
 			previewCertificateType: formData.previewCertificateType,
 			previewCustomCertResolver: formData.previewCustomCertResolver,
+			previewRequireCollaboratorPermissions:
+				formData.previewRequireCollaboratorPermissions,
 		})
 			.then(() => {
 				toast.success("Preview Deployments settings updated");
@@ -312,6 +318,32 @@ export const ShowPreviewSettings = ({ applicationId }: Props) => {
 									</div>
 								</div>
 
+								<div className="grid gap-4 lg:grid-cols-2">
+									<FormField
+										control={form.control}
+										name="previewRequireCollaboratorPermissions"
+										render={({ field }) => (
+											<FormItem className="flex flex-row items-center justify-between p-3 mt-4 border rounded-lg shadow-sm col-span-2">
+												<div className="space-y-0.5">
+													<FormLabel>
+														Require Collaborator Permissions
+													</FormLabel>
+													<FormDescription>
+														Require collaborator permissions to preview
+														deployments.
+													</FormDescription>
+												</div>
+												<FormControl>
+													<Switch
+														checked={field.value}
+														onCheckedChange={field.onChange}
+													/>
+												</FormControl>
+											</FormItem>
+										)}
+									/>
+								</div>
+
 								<FormField
 									control={form.control}
 									name="env"

apps/dokploy/drizzle/0103_cultured_pestilence.sql

@@ -0,0 +1 @@
+ALTER TABLE "application" ADD COLUMN "previewRequireCollaboratorPermissions" boolean DEFAULT true;

apps/dokploy/drizzle/meta/_journal.json

@@ -722,6 +722,13 @@
       "when": 1751848685503,
       "tag": "0102_opposite_grandmaster",
       "breakpoints": true
+    },
+    {
+      "idx": 103,
+      "version": "7",
+      "when": 1752465764072,
+      "tag": "0103_cultured_pestilence",
+      "breakpoints": true
     }
   ]
 }

apps/dokploy/pages/api/deploy/github.ts

@@ -10,6 +10,9 @@ import {
 	findPreviewDeploymentsByPullRequestId,
 	removePreviewDeployment,
 	shouldDeploy,
+	findGithubById,
+	checkUserRepositoryPermissions,
+	createSecurityBlockedComment,
 } from "@dokploy/server";
 import { Webhooks } from "@octokit/webhooks";
 import { and, eq } from "drizzle-orm";
@@ -346,6 +349,18 @@ export default async function handler(
 			const deploymentHash = githubBody?.pull_request?.head?.sha;
 			const branch = githubBody?.pull_request?.base?.ref;
 			const owner = githubBody?.repository?.owner?.login;
+			const prAuthor = githubBody?.pull_request?.user?.login;
+
+			// Validate PR author information is present
+			if (!prAuthor) {
+				console.warn(
+					"⚠️ SECURITY: PR author information missing in webhook payload",
+				);
+				res.status(400).json({
+					message: "PR author information missing",
+				});
+				return;
+			}
 
 			const apps = await db.query.applications.findMany({
 				where: and(
@@ -361,15 +376,74 @@ export default async function handler(
 				},
 			});
 
+			// SECURITY: Check collaborator permissions per application setting
+			const secureApps: typeof apps = [];
+			const blockedApps: string[] = [];
+			let userPermission: string | null = null;
+
+			for (const app of apps) {
+				// If the app requires collaborator permissions, verify them
+				if (app.previewRequireCollaboratorPermissions !== false) {
+					try {
+						const githubProvider = await findGithubById(githubResult.githubId);
+						const { hasWriteAccess, permission } =
+							await checkUserRepositoryPermissions(
+								githubProvider,
+								owner,
+								repository,
+								prAuthor,
+							);
+
+						userPermission = permission; // Store permission for comment
+
+						if (!hasWriteAccess) {
+							console.warn(
+								`🚨 SECURITY: Blocked preview deployment for ${app.name} from unauthorized user ${prAuthor} on ${owner}/${repository}. Permission: ${permission || "none"}`,
+							);
+							blockedApps.push(app.name);
+							continue;
+						}
+
+						console.log(
+							`✅ SECURITY: Preview deployment authorized for ${app.name} from user ${prAuthor} on ${owner}/${repository}. Permission: ${permission}`,
+						);
+					} catch (error) {
+						console.error(
+							`Error validating PR author permissions for ${app.name}:`,
+							error,
+						);
+						blockedApps.push(app.name);
+						continue; // Skip this app on error
+					}
+				} else {
+					console.warn(
+						`⚠️  SECURITY: Preview deployment for ${app.name} allows deployment from any PR author (security check disabled)`,
+					);
+				}
+				secureApps.push(app);
+			}
+
 			const prBranch = githubBody?.pull_request?.head?.ref;
 
 			const prNumber = githubBody?.pull_request?.number;
 			const prTitle = githubBody?.pull_request?.title;
 			const prURL = githubBody?.pull_request?.html_url;
 
-			for (const app of apps) {
+			// Create security notification comment if any apps were blocked
+			if (blockedApps.length > 0) {
+				await createSecurityBlockedComment({
+					owner,
+					repository,
+					prNumber: Number.parseInt(prNumber),
+					prAuthor,
+					permission: userPermission,
+					githubId: githubResult.githubId,
+				});
+			}
+
+			for (const app of secureApps) {
 				const previewLimit = app?.previewLimit || 0;
-				if (app?.previewDeployments?.length > previewLimit) {
+				if (app?.previewDeployments?.length >= previewLimit) {
 					continue;
 				}
 				const previewDeploymentResult =

packages/server/src/db/schema/application.ts

@@ -131,6 +131,10 @@ export const applications = pgTable("application", {
 	isPreviewDeploymentsActive: boolean("isPreviewDeploymentsActive").default(
 		false,
 	),
+	// Security: Require collaborator permissions for preview deployments
+	previewRequireCollaboratorPermissions: boolean(
+		"previewRequireCollaboratorPermissions",
+	).default(true),
 	rollbackActive: boolean("rollbackActive").default(false),
 	buildArgs: text("buildArgs"),
 	memoryReservation: text("memoryReservation"),
@@ -428,6 +432,7 @@ const createSchema = createInsertSchema(applications, {
 	previewHttps: z.boolean().optional(),
 	previewPath: z.string().optional(),
 	previewCertificateType: z.enum(["letsencrypt", "none", "custom"]).optional(),
+	previewRequireCollaboratorPermissions: z.boolean().optional(),
 	watchPaths: z.array(z.string()).optional(),
 	cleanCache: z.boolean().optional(),
 });

packages/server/src/index.ts

@@ -45,6 +45,7 @@ export * from "./setup/traefik-setup";
 export * from "./setup/server-validate";
 export * from "./setup/server-audit";
 export * from "./utils/watch-paths/should-deploy";
+export * from "./utils/providers/github";
 export * from "./utils/backups/index";
 export * from "./utils/backups/mariadb";
 export * from "./utils/backups/mongo";

packages/server/src/services/github.ts

@@ -192,3 +192,156 @@ export const createPreviewDeploymentComment = async ({
 		pullRequestCommentId: `${issue.data.id}`,
 	}).then((response) => response[0]);
 };
+
+/**
+ * Generate security notification message for blocked PR deployments
+ */
+export const getSecurityBlockedMessage = (
+	prAuthor: string,
+	repositoryName: string,
+	permission: string | null,
+) => {
+	return `### 🚨 Preview Deployment Blocked - Security Protection
+
+**Your pull request was blocked from triggering preview deployments**
+
+#### Why was this blocked?
+- **User**: \`${prAuthor}\`
+- **Repository**: \`${repositoryName}\`
+- **Permission Level**: \`${permission || "none"}\`
+- **Required Level**: \`write\`, \`maintain\`, or \`admin\`
+
+#### How to resolve this:
+
+**Option 1: Get Collaborator Access (Recommended)**
+Ask a repository maintainer to invite you as a collaborator with **write permissions** or higher.
+
+**Option 2: Request Permission Override**
+Ask a repository administrator to disable security validation for this specific application if appropriate.
+
+#### For Repository Administrators:
+To disable this security check (⚠️ **not recommended for public repositories**):
+Enter to preview settings and disable the security check.
+
+---
+*This security measure protects against malicious code execution in preview deployments. Only trusted collaborators should have the ability to trigger deployments.*
+
+<details>
+<summary>🛡️ Learn more about this security feature</summary>
+
+This protection prevents unauthorized users from:
+- Executing malicious code on the deployment server
+- Accessing environment variables and secrets
+- Potentially compromising the infrastructure
+
+Preview deployments are powerful but require trust. Only users with repository write access can trigger them.
+</details>`;
+};
+
+/**
+ * Check if a security notification comment already exists on a GitHub PR
+ * This prevents creating duplicate security comments on subsequent pushes
+ */
+export const hasExistingSecurityComment = async ({
+	owner,
+	repository,
+	prNumber,
+	githubId,
+}: {
+	owner: string;
+	repository: string;
+	prNumber: number;
+	githubId: string;
+}): Promise<boolean> => {
+	try {
+		const github = await findGithubById(githubId);
+		const octokit = authGithub(github);
+
+		// Get all comments for this PR
+		const { data: comments } = await octokit.rest.issues.listComments({
+			owner,
+			repo: repository,
+			issue_number: prNumber,
+		});
+
+		// Check if any comment contains our security notification marker
+		const securityCommentExists = comments.some((comment) =>
+			comment.body?.includes(
+				"🚨 Preview Deployment Blocked - Security Protection",
+			),
+		);
+
+		return securityCommentExists;
+	} catch (error) {
+		console.error(
+			`❌ Failed to check existing comments on PR #${prNumber}:`,
+			error,
+		);
+		// If we can't check, assume no comment exists to avoid blocking functionality
+		return false;
+	}
+};
+
+/**
+ * Create a security notification comment on a GitHub PR
+ */
+export const createSecurityBlockedComment = async ({
+	owner,
+	repository,
+	prNumber,
+	prAuthor,
+	permission,
+	githubId,
+}: {
+	owner: string;
+	repository: string;
+	prNumber: number;
+	prAuthor: string;
+	permission: string | null;
+	githubId: string;
+}) => {
+	try {
+		// Check if a security comment already exists to prevent duplicates
+		const commentExists = await hasExistingSecurityComment({
+			owner,
+			repository,
+			prNumber,
+			githubId,
+		});
+
+		if (commentExists) {
+			console.log(
+				`ℹ️  Security notification comment already exists on PR #${prNumber}, skipping duplicate`,
+			);
+			return null;
+		}
+
+		const github = await findGithubById(githubId);
+		const octokit = authGithub(github);
+
+		const securityMessage = getSecurityBlockedMessage(
+			prAuthor,
+			repository,
+			permission,
+		);
+
+		const issue = await octokit.rest.issues.createComment({
+			owner,
+			repo: repository,
+			issue_number: prNumber,
+			body: securityMessage,
+		});
+
+		console.log(
+			`✅ Security notification comment created on PR #${prNumber}: ${issue.data.html_url}`,
+		);
+		return issue.data;
+	} catch (error) {
+		console.error(
+			`❌ Failed to create security comment on PR #${prNumber}:`,
+			error,
+		);
+		// Don't throw error - security comment is nice-to-have, not critical
+		return null;
+	}
+};

packages/server/src/utils/providers/github.ts

@@ -45,6 +45,49 @@ export const getGithubToken = async (
 	return installation.token;
 };
 
+/**
+ * Check if a GitHub user has write/admin permissions on a repository
+ * This is used to validate PR authors before allowing preview deployments
+ */
+export const checkUserRepositoryPermissions = async (
+	githubProvider: Github,
+	owner: string,
+	repo: string,
+	username: string,
+): Promise<{ hasWriteAccess: boolean; permission: string | null }> => {
+	try {
+		const octokit = authGithub(githubProvider);
+
+		// Check if user is a collaborator with write permissions
+		const { data: permission } =
+			await octokit.rest.repos.getCollaboratorPermissionLevel({
+				owner,
+				repo,
+				username,
+			});
+
+		// Allow only users with 'write', 'admin', or 'maintain' permissions
+		// Currently exists Read, Triage, Write, Maintain, Admin
+		const allowedPermissions = ["write", "admin", "maintain"];
+		const hasWriteAccess = allowedPermissions.includes(permission.permission);
+
+		return {
+			hasWriteAccess,
+			permission: permission.permission,
+		};
+	} catch (error) {
+		// If user is not a collaborator, GitHub API returns 404
+		console.warn(
+			`User ${username} is not a collaborator of ${owner}/${repo}:`,
+			error,
+		);
+		return {
+			hasWriteAccess: false,
+			permission: null,
+		};
+	}
+};
+
 export const haveGithubRequirements = (githubProvider: Github) => {
 	return !!(
 		githubProvider?.githubAppId &&