coder · SasSwart · Jun 12, 2025 · Jun 12, 2025 · Jul 14, 2025 · Jul 15, 2025
diff --git a/coderd/database/dbauthz/dbauthz.go b/coderd/database/dbauthz/dbauthz.go
@@ -485,6 +485,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
@@ -161,7 +161,7 @@ func (api *API) listMembers(rw http.ResponseWriter, r *http.Request) {
 	members, err := api.Database.OrganizationMembers(ctx, database.OrganizationMembersParams{
 		OrganizationID: organization.ID,
 		UserID:         uuid.Nil,
-		IncludeSystem:  false,
+		IncludeSystem:  true,
 	})
 	if httpapi.Is404Error(err) {
 		httpapi.ResourceNotFound(rw)
@@ -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:  true,
 		// #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/coderd/members_test.go b/coderd/members_test.go
@@ -7,6 +7,7 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"github.com/coder/coder/v2/coderd/coderdtest"
+	"github.com/coder/coder/v2/coderd/database"
 	"github.com/coder/coder/v2/coderd/database/db2sdk"
 	"github.com/coder/coder/v2/coderd/rbac"
 	"github.com/coder/coder/v2/codersdk"
@@ -62,9 +63,9 @@ func TestListMembers(t *testing.T) {
 		ctx := testutil.Context(t, testutil.WaitShort)
 		members, err := client.OrganizationMembers(ctx, first.OrganizationID)
 		require.NoError(t, err)
-		require.Len(t, members, 2)
+		require.Len(t, members, 3)
 		require.ElementsMatch(t,
-			[]uuid.UUID{first.UserID, user.ID},
+			[]uuid.UUID{first.UserID, user.ID, database.PrebuildsSystemUserID},
 			db2sdk.List(members, onlyIDs))
 	})
 }

diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md
@@ -235,12 +235,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/groups.go b/enterprise/coderd/groups.go
@@ -156,7 +156,7 @@ func (api *API) patchGroup(rw http.ResponseWriter, r *http.Request) {
 
 	currentMembers, err := api.Database.GetGroupMembersByGroupID(ctx, database.GetGroupMembersByGroupIDParams{
 		GroupID:       group.ID,
-		IncludeSystem: false,
+		IncludeSystem: true,
 	})
 	if err != nil {
 		httpapi.InternalServerError(rw, err)
@@ -180,7 +180,7 @@ func (api *API) patchGroup(rw http.ResponseWriter, r *http.Request) {
 		_, err := database.ExpectOne(api.Database.OrganizationMembers(ctx, database.OrganizationMembersParams{
 			OrganizationID: group.OrganizationID,
 			UserID:         uuid.MustParse(id),
-			IncludeSystem:  false,
+			IncludeSystem:  true,
 		}))
 		if errors.Is(err, sql.ErrNoRows) {
 			httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
@@ -296,7 +296,7 @@ func (api *API) patchGroup(rw http.ResponseWriter, r *http.Request) {
 
 	patchedMembers, err := api.Database.GetGroupMembersByGroupID(ctx, database.GetGroupMembersByGroupIDParams{
 		GroupID:       group.ID,
-		IncludeSystem: false,
+		IncludeSystem: true,
 	})
 	if err != nil {
 		httpapi.InternalServerError(rw, err)
@@ -307,7 +307,7 @@ func (api *API) patchGroup(rw http.ResponseWriter, r *http.Request) {
 
 	memberCount, err := api.Database.GetGroupMembersCountByGroupID(ctx, database.GetGroupMembersCountByGroupIDParams{
 		GroupID:       group.ID,
-		IncludeSystem: false,
+		IncludeSystem: true,
 	})
 	if err != nil {
 		httpapi.InternalServerError(rw, err)
@@ -353,7 +353,7 @@ func (api *API) deleteGroup(rw http.ResponseWriter, r *http.Request) {
 
 	groupMembers, getMembersErr := api.Database.GetGroupMembersByGroupID(ctx, database.GetGroupMembersByGroupIDParams{
 		GroupID:       group.ID,
-		IncludeSystem: false,
+		IncludeSystem: true,
 	})
 	if getMembersErr != nil {
 		httpapi.InternalServerError(rw, getMembersErr)
@@ -407,7 +407,7 @@ func (api *API) group(rw http.ResponseWriter, r *http.Request) {
 
 	users, err := api.Database.GetGroupMembersByGroupID(ctx, database.GetGroupMembersByGroupIDParams{
 		GroupID:       group.ID,
-		IncludeSystem: false,
+		IncludeSystem: true,
 	})
 	if err != nil && !errors.Is(err, sql.ErrNoRows) {
 		httpapi.InternalServerError(rw, err)
@@ -416,7 +416,7 @@ func (api *API) group(rw http.ResponseWriter, r *http.Request) {
 
 	memberCount, err := api.Database.GetGroupMembersCountByGroupID(ctx, database.GetGroupMembersCountByGroupIDParams{
 		GroupID:       group.ID,
-		IncludeSystem: false,
+		IncludeSystem: true,
 	})
 	if err != nil {
 		httpapi.InternalServerError(rw, err)
@@ -512,15 +512,15 @@ func (api *API) groups(rw http.ResponseWriter, r *http.Request) {
 	for _, group := range groups {
 		members, err := api.Database.GetGroupMembersByGroupID(ctx, database.GetGroupMembersByGroupIDParams{
 			GroupID:       group.Group.ID,
-			IncludeSystem: false,
+			IncludeSystem: true,
 		})
 		if err != nil {
 			httpapi.InternalServerError(rw, err)
 			return
 		}
 		memberCount, err := api.Database.GetGroupMembersCountByGroupID(ctx, database.GetGroupMembersCountByGroupIDParams{
 			GroupID:       group.Group.ID,
-			IncludeSystem: false,
+			IncludeSystem: true,
 		})
 		if err != nil {
 			httpapi.InternalServerError(rw, err)

diff --git a/enterprise/coderd/groups_test.go b/enterprise/coderd/groups_test.go
@@ -862,12 +862,12 @@ func TestGroup(t *testing.T) {
 		// The 'Everyone' group always has an ID that matches the organization ID.
 		group, err := userAdminClient.Group(ctx, user.OrganizationID)
 		require.NoError(t, err)
-		require.Len(t, group.Members, 4)
+		require.Len(t, group.Members, 5)
 		require.Equal(t, "Everyone", group.Name)
 		require.Equal(t, user.OrganizationID, group.OrganizationID)
 		require.Contains(t, group.Members, user1.ReducedUser)
 		require.Contains(t, group.Members, user2.ReducedUser)
-		require.NotContains(t, group.Members, prebuildsUser.ReducedUser)
+		require.Contains(t, group.Members, prebuildsUser.ReducedUser)
 	})
 }
 

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        = "coder_prebuilt_workspaces"
+	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.
 //
-// This method does not have an opinion on transaction or lock management. These responsibilities are left to the caller.
+// 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.
+//
+// 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,74 @@ 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{
+		// 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,
-			UserID:         userID,
-			CreatedAt:      s.clock.Now(),
-			UpdatedAt:      s.clock.Now(),
-			Roles:          []string{},
+			AvatarURL:      "",
+			QuotaAllowance: 0, // Default quota of 0, users should set this based on their needs
+		})
+		if err != nil {
+			// If the group already exists, try to get it
+			if !database.IsUniqueViolation(err) {
+				membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("create prebuilds group: %w", err))
+				continue
+			}
+			prebuildsGroup, err = s.store.GetGroupByOrgAndName(ctx, database.GetGroupByOrgAndNameParams{
+				OrganizationID: preset.OrganizationID,
+				Name:           PrebuiltWorkspacesGroupName,
+			})
+			if err != nil {
+				membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("get existing 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