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,14 @@ var (
 					rbac.ResourceFile.Type: {
 						policy.ActionRead,
 					},
+					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,12 @@ 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
-  -- Filter by system type
-	AND CASE
-		WHEN @include_system::bool THEN TRUE
-		ELSE
-			is_system = false
-	END
+  -- Conditionally include system users based on @include_system flag
+	AND (@include_system OR is_system = false)
-  -- Filter by system type
-	AND CASE
-		WHEN @include_system::bool THEN TRUE
-		ELSE
-			is_system = false
-	END
+  -- Conditionally include system users based on @include_system flag
+	AND (@include_system OR is_system = false)
 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
@@ -44,37 +44,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:           "prebuilds",
+			DisplayName:    "Prebuilds",
 			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:           "prebuilds",
+			})
+			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