coder · SasSwart · Aug 27, 2025 · Jun 12, 2025 · Jun 12, 2025 · Jul 14, 2025
diff --git a/coderd/database/dbauthz/dbauthz.go b/coderd/database/dbauthz/dbauthz.go
@@ -487,6 +487,16 @@ var (
 					rbac.ResourceFile.Type: {
 						policy.ActionRead,
 					},
+					// Needs to be able to add the prebuilds system user to the "prebuilds" group in each organization that needs prebuilt workspaces
+					// so that prebuilt workspaces can be scheduled and owned in those organizations.
+					rbac.ResourceGroup.Type: {
+						policy.ActionRead,
+						policy.ActionCreate,
+						policy.ActionUpdate,
+					},
+					rbac.ResourceGroupMember.Type: {
+						policy.ActionRead,
+					},
 				}),
 			},
 		}),

diff --git a/coderd/database/queries.sql.go b/coderd/database/queries.sql.go
diff --git a/coderd/database/queries/organizationmembers.sql b/coderd/database/queries/organizationmembers.sql
@@ -89,6 +89,8 @@ WHERE
 			organization_id = @organization_id
 		ELSE true
 	END
+  -- Filter by system type
+	AND CASE WHEN @include_system::bool THEN TRUE ELSE is_system = false END
 ORDER BY
 	-- Deterministic and consistent ordering of all users. This is to ensure consistent pagination.
 	LOWER(username) ASC OFFSET @offset_opt

diff --git a/coderd/members.go b/coderd/members.go
@@ -203,6 +203,7 @@ func (api *API) paginatedMembers(rw http.ResponseWriter, r *http.Request) {
 
 	paginatedMemberRows, err := api.Database.PaginatedOrganizationMembers(ctx, database.PaginatedOrganizationMembersParams{
 		OrganizationID: organization.ID,
+		IncludeSystem:  false,
 		// #nosec G115 - Pagination limits are small and fit in int32
 		LimitOpt: int32(paginationParams.Limit),
 		// #nosec G115 - Pagination offsets are small and fit in int32

diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md
@@ -233,12 +233,18 @@ The system always maintains the desired number of prebuilt workspaces for the ac
 
 ### Managing resource quotas
 
-Prebuilt workspaces can be used in conjunction with [resource quotas](../../users/quotas.md).
+To help prevent unexpected infrastructure costs, prebuilt workspaces can be used in conjunction with [resource quotas](../../users/quotas.md).
 Because unclaimed prebuilt workspaces are owned by the `prebuilds` user, you can:
 
 1. Configure quotas for any group that includes this user.
 1. Set appropriate limits to balance prebuilt workspace availability with resource constraints.
 
+When prebuilt workspaces are configured for an organization, Coder creates a "prebuilds" group in that organization and adds the prebuilds user to it. This group has a default quota allowance of 0, which you should adjust based on your needs:
+
+- **Set a quota allowance** on the "prebuilds" group to control how many prebuilt workspaces can be provisioned
+- **Monitor usage** to ensure the quota is appropriate for your desired number of prebuilt instances
+- **Adjust as needed** based on your template costs and desired prebuilt workspace pool size
+
 If a quota is exceeded, the prebuilt workspace will fail provisioning the same way other workspaces do.
 
 ### Template configuration best practices

diff --git a/enterprise/coderd/prebuilds/membership.go b/enterprise/coderd/prebuilds/membership.go
@@ -12,6 +12,11 @@ import (
 	"github.com/coder/quartz"
 )
 
+const (
+	PrebuiltWorkspacesGroupName        = "coderprebuiltworkspaces"
+	PrebuiltWorkspacesGroupDisplayName = "Prebuilt Workspaces"
+)
+
 // StoreMembershipReconciler encapsulates the responsibility of ensuring that the prebuilds system user is a member of all
 // organizations for which prebuilt workspaces are requested. This is necessary because our data model requires that such
 // prebuilt workspaces belong to a member of the organization of their eventual claimant.
@@ -27,11 +32,16 @@ func NewStoreMembershipReconciler(store database.Store, clock quartz.Clock) Stor
 	}
 }
 
-// ReconcileAll compares the current membership of a user to the membership required in order to create prebuilt workspaces.
-// If the user in question is not yet a member of an organization that needs prebuilt workspaces, ReconcileAll will create
-// the membership required.
+// ReconcileAll compares the current organization and group memberships of a user to the memberships required
+// in order to create prebuilt workspaces. If the user in question is not yet a member of an organization that
+// needs prebuilt workspaces, ReconcileAll will create the membership required.
+//
+// To facilitate quota management, ReconcileAll will ensure:
+// * the existence of a group (defined by PrebuiltWorkspacesGroupName) in each organization that needs prebuilt workspaces
+// * that the prebuilds system user belongs to the group in each organization that needs prebuilt workspaces
+// * that the group has a quota of 0 by default, which users can adjust based on their needs.
 //
-// This method does not have an opinion on transaction or lock management. These responsibilities are left to the caller.
+// ReconcileAll does not have an opinion on transaction or lock management. These responsibilities are left to the caller.
 func (s StoreMembershipReconciler) ReconcileAll(ctx context.Context, userID uuid.UUID, presets []database.GetTemplatePresetsWithPrebuildsRow) error {
 	organizationMemberships, err := s.store.GetOrganizationsByUserID(ctx, database.GetOrganizationsByUserIDParams{
 		UserID: userID,
@@ -44,37 +54,80 @@ func (s StoreMembershipReconciler) ReconcileAll(ctx context.Context, userID uuid
 		return xerrors.Errorf("determine prebuild organization membership: %w", err)
 	}
 
-	systemUserMemberships := make(map[uuid.UUID]struct{}, 0)
+	orgMemberships := make(map[uuid.UUID]struct{}, 0)
 	defaultOrg, err := s.store.GetDefaultOrganization(ctx)
 	if err != nil {
 		return xerrors.Errorf("get default organization: %w", err)
 	}
-	systemUserMemberships[defaultOrg.ID] = struct{}{}
+	orgMemberships[defaultOrg.ID] = struct{}{}
 	for _, o := range organizationMemberships {
-		systemUserMemberships[o.ID] = struct{}{}
+		orgMemberships[o.ID] = struct{}{}
 	}
 
 	var membershipInsertionErrors error
 	for _, preset := range presets {
-		_, alreadyMember := systemUserMemberships[preset.OrganizationID]
-		if alreadyMember {
-			continue
+		_, alreadyOrgMember := orgMemberships[preset.OrganizationID]
+		if !alreadyOrgMember {
+			// Add the organization to our list of memberships regardless of potential failure below
+			// to avoid a retry that will probably be doomed anyway.
+			orgMemberships[preset.OrganizationID] = struct{}{}
+
+			// Insert the missing membership
+			_, err = s.store.InsertOrganizationMember(ctx, database.InsertOrganizationMemberParams{
+				OrganizationID: preset.OrganizationID,
+				UserID:         userID,
+				CreatedAt:      s.clock.Now(),
+				UpdatedAt:      s.clock.Now(),
+				Roles:          []string{},
+			})
+			if err != nil {
+				membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("insert membership for prebuilt workspaces: %w", err))
+				continue
+			}
 		}
-		// Add the organization to our list of memberships regardless of potential failure below
-		// to avoid a retry that will probably be doomed anyway.
-		systemUserMemberships[preset.OrganizationID] = struct{}{}
 
-		// Insert the missing membership
-		_, err = s.store.InsertOrganizationMember(ctx, database.InsertOrganizationMemberParams{
+		// determine whether the org already has a prebuilds group
+		prebuildsGroupExists := true
+		prebuildsGroup, err := s.store.GetGroupByOrgAndName(ctx, database.GetGroupByOrgAndNameParams{
 			OrganizationID: preset.OrganizationID,
-			UserID:         userID,
-			CreatedAt:      s.clock.Now(),
-			UpdatedAt:      s.clock.Now(),
-			Roles:          []string{},
+			Name:           PrebuiltWorkspacesGroupName,
+		})
+		if err != nil {
+			if !xerrors.Is(err, sql.ErrNoRows) {
+				membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("get prebuilds group: %w", err))
+				continue
+			}
+			prebuildsGroupExists = false
+		}
+
+		// if the prebuilds group does not exist, create it
+		if !prebuildsGroupExists {
+			// create a "prebuilds" group in the organization and add the system user to it
+			// this group will have a quota of 0 by default, which users can adjust based on their needs
+			prebuildsGroup, err = s.store.InsertGroup(ctx, database.InsertGroupParams{
+				ID:             uuid.New(),
+				Name:           PrebuiltWorkspacesGroupName,
+				DisplayName:    PrebuiltWorkspacesGroupDisplayName,
+				OrganizationID: preset.OrganizationID,
+				AvatarURL:      "",
+				QuotaAllowance: 0, // Default quota of 0, users should set this based on their needs
+			})
+			if err != nil {
+				membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("create prebuilds group: %w", err))
+				continue
+			}
+		}
+
+		// add the system user to the prebuilds group
+		err = s.store.InsertGroupMember(ctx, database.InsertGroupMemberParams{
+			GroupID: prebuildsGroup.ID,
+			UserID:  userID,
 		})
 		if err != nil {
-			membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("insert membership for prebuilt workspaces: %w", err))
-			continue
+			// ignore unique violation errors as the user might already be in the group
+			if !database.IsUniqueViolation(err) {
+				membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("add system user to prebuilds group: %w", err))
+			}
 		}
 	}
 	return membershipInsertionErrors