Aug 8, 2025 · Jun 12, 2025 · Jun 12, 2025 · Jul 14, 2025 · Jul 15, 2025 · Jul 29, 2025
diff --git a/coderd/database/dbauthz/dbauthz.go b/coderd/database/dbauthz/dbauthz.go
 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
 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

 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

 ### 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
 "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.
 }
 }

 // ReconcileAll compares the currentmembershipof a user to themembership 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 currentorganization and group membershipsof a user to thememberships 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 createthe 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,
 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
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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,
		},
SasSwart marked this conversation as resolved. Show resolvedHide resolved
		}),
		},
		}),
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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:
SasSwart marked this conversation as resolved. Show resolvedHide resolved

		- 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
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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.
Expand All		@@ -27,11 +32,16 @@ func NewStoreMembershipReconciler(store database.Store, clock quartz.Clock) Stor
		}
		}

		// ReconcileAll compares the currentmembershipof a user to themembership 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 currentorganization and group membershipsof a user to thememberships 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 createthe 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,
Expand All		@@ -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{
SasSwart marked this conversation as resolved. Show resolvedHide resolved
		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
Expand Down