Apply free Service Desk email limits to newly paid namespaces
What does this MR do and why?
Gives newly paid top-level namespaces on GitLab.com the Free plan Service Desk email rate limits for a set number of days (default 7) after they become paid.
This makes the volume of emails to external participants increase gradually: a namespace gets its plan's full limits only after it has been paying for a while.
How it works
- Where it applies. Only in
ServiceDesk::EmailRateLimiter, which limits every email to external participants: the ticket confirmation email, comment notifications on any issue or work item with email participants, and the email sent when a participant is added (/add_emailor CC). Emails on Push and pipeline emails keep their plan limits.Gitlab::Email::NamespaceRateLimitergets an optionalplan_limits:callable, defaulting to the namespace's plan limits. It's only called once limiting is enabled, so the probation lookup never runs whileservice_desk_email_rate_limitis off.ServiceDesk::EmailRateLimiterpasses its ownplan_limits, which the EE module overrides to return the Free plan's limits during probation.
- When a namespace is on probation. All of these hold:
- It's on GitLab.com.
- It's on a paid plan that isn't a trial. Open source program namespaces are excluded because GitLab approves them; they aren't purchased.
- The
service_desk_paid_namespace_probationfeature flag is enabled for the root namespace. - It became paid less than
service_desk_paid_namespace_probation_daysago.
- When "became paid" happened. This is read from
gitlab_subscription_histories, not fromstart_date, becausestart_datemoves forward on every renewal and would put long-paying customers back on probation. Each history row stores the state a change replaced, so a recent row that wasn't on a paid plan marks an upgrade. A paying customer's Ultimate trial (ultimate_trial_paid_customer) counts as paid. - Cost. The check runs only for paid namespaces with the flag enabled. It skips the history query when the subscription itself is new, otherwise it's a single
EXISTS, and the result is cached for the request. - Exemptions. Exempt a legitimate namespace by opting it out of the feature flag (
value=opt_outin the Features API). GitLab'sFeaturewrapper honours actor opt-outs even when a flag is enabled globally. - Admin setting.
service_desk_paid_namespace_probation_daysis stored in the existingrate_limitsJSONB column, so no migration is needed.0disables the probation. It shows in Admin > Settings > Network and can be saved only on GitLab.com when the flag is enabled globally. It isn't exposed through the REST API. - Self-managed. Gated by the existing
gitlab_com_subscriptionsSaaS feature, because self-managed licenses cover the whole instance and there are no per-namespace subscriptions.
No changelog entry or user docs yet: the wip flag is off by default. Docs will follow with the rollout.
Database
New read query, run by ServiceDesk::PaidNamespaceProbation#became_paid_since? for every Service Desk email batch (ticket confirmation, comment notifications to external participants, and new participant emails) once service_desk_email_rate_limit is enabled for the namespace. It's skipped unless the root namespace is on GitLab.com, on a paid non-trial plan, and has the probation flag enabled. It's also skipped when the subscription was created inside the probation window. The result is cached per request or job. Emails on Push and pipeline emails don't run it.
1. Whether the namespace became paid within the probation window
SELECT 1 AS one FROM "gitlab_subscription_histories"
WHERE "gitlab_subscription_histories"."namespace_id" = <namespace_id>
AND ("gitlab_subscription_histories"."hosted_plan_name_uid" NOT IN (3, 4, 5, 6, 7, 10, 11)
OR "gitlab_subscription_histories"."hosted_plan_name_uid" IS NULL
OR "gitlab_subscription_histories"."trial" = TRUE AND "gitlab_subscription_histories"."hosted_plan_name_uid" != 10)
AND "gitlab_subscription_histories"."created_at" >= '<now - probation_days>'
LIMIT 1The hosted_plan_name_uid values are the fixed GitlabSubscriptions::SystemDefined::Plan ids. Plans are from EXPLAIN (ANALYZE, BUFFERS) on a gitlab-production-main Database Lab clone, all cold cache.
Worst case: the namespace with the most history rows and no match, so every row is read (Index Scan on i_gitlab_subscription_histories_on_namespace_change_type_plan, 29.4 ms, buffers: 7 hit / 1,386 read)
Plan
Limit (cost=0.43..114.36 rows=1 width=4) (actual time=29.379..29.380 rows=0 loops=1)
Buffers: shared hit=7 read=1386
I/O Timings: read=26.649 write=0.000
-> Index Scan using i_gitlab_subscription_histories_on_namespace_change_type_plan on public.gitlab_subscription_histories (cost=0.43..1595.35 rows=14 width=4) (actual time=29.377..29.378 rows=0 loops=1)
Index Cond: (gitlab_subscription_histories.namespace_id = <namespace_id>)
Filter: ((gitlab_subscription_histories.created_at >= '2026-10-22 08:00:00+00'::timestamp with time zone) AND ((gitlab_subscription_histories.hosted_plan_name_uid <> ALL ('{3,4,5,6,7,10,11}'::integer[])) OR (gitlab_subscription_histories.hosted_plan_name_uid IS NULL) OR (gitlab_subscription_histories.trial AND (gitlab_subscription_histories.hosted_plan_name_uid <> 10))))
Rows Removed by Filter: 1389
Buffers: shared hit=7 read=1386
I/O Timings: read=26.649 write=0.000A large paid namespace with no match (same index, 16.6 ms, buffers: 59 hit / 622 read)
Plan
Limit (cost=0.43..110.23 rows=1 width=4) (actual time=16.643..16.644 rows=0 loops=1)
Buffers: shared hit=59 read=622
I/O Timings: read=14.991 write=0.000
-> Index Scan using i_gitlab_subscription_histories_on_namespace_change_type_plan on public.gitlab_subscription_histories (cost=0.43..988.57 rows=9 width=4) (actual time=16.641..16.642 rows=0 loops=1)
Index Cond: (gitlab_subscription_histories.namespace_id = <namespace_id>)
Filter: ((gitlab_subscription_histories.created_at >= '2026-10-22 08:00:00+00'::timestamp with time zone) AND ((gitlab_subscription_histories.hosted_plan_name_uid <> ALL ('{3,4,5,6,7,10,11}'::integer[])) OR (gitlab_subscription_histories.hosted_plan_name_uid IS NULL) OR (gitlab_subscription_histories.trial AND (gitlab_subscription_histories.hosted_plan_name_uid <> 10))))
Rows Removed by Filter: 687
Buffers: shared hit=59 read=622
I/O Timings: read=14.991 write=0.000A namespace that upgraded within the window, so it stops at the first match (same index, 3.0 ms, buffers: 4 hit / 67 read)
Plan
Limit (cost=0.43..7.70 rows=1 width=4) (actual time=3.039..3.040 rows=1 loops=1)
Buffers: shared hit=4 read=67
I/O Timings: read=2.743 write=0.000
-> Index Scan using i_gitlab_subscription_histories_on_namespace_change_type_plan on public.gitlab_subscription_histories (cost=0.43..7.70 rows=1 width=4) (actual time=3.037..3.038 rows=1 loops=1)
Index Cond: (gitlab_subscription_histories.namespace_id = <namespace_id>)
Filter: ((gitlab_subscription_histories.created_at >= '2026-10-22 08:00:00+00'::timestamp with time zone) AND ((gitlab_subscription_histories.hosted_plan_name_uid <> ALL ('{3,4,5,6,7,10,11}'::integer[])) OR (gitlab_subscription_histories.hosted_plan_name_uid IS NULL) OR (gitlab_subscription_histories.trial AND (gitlab_subscription_histories.hosted_plan_name_uid <> 10))))
Rows Removed by Filter: 67
Buffers: shared hit=4 read=67
I/O Timings: read=2.743 write=0.000The existing index only covers the namespace_id lookup, so the remaining conditions are applied as a filter on that namespace's history rows. An index on (namespace_id, created_at) would bring the worst case down to 0.2 ms (5 hit / 3 read). Following database review, it's left out for now and can be added in a follow-up if we see performance issues.
Plan with a test (namespace_id, created_at) index on the clone
Limit (cost=0.43..1.78 rows=1 width=4) (actual time=0.177..0.178 rows=0 loops=1)
Buffers: shared hit=5 read=3
I/O Timings: read=0.120 write=0.000
-> Index Scan using tmp_idx_gsh_ns_created_at on public.gitlab_subscription_histories (cost=0.43..19.31 rows=14 width=4) (actual time=0.176..0.177 rows=0 loops=1)
Index Cond: ((gitlab_subscription_histories.namespace_id = <namespace_id>) AND (gitlab_subscription_histories.created_at >= '2026-10-22 08:00:00+00'::timestamp with time zone))
Filter: ((gitlab_subscription_histories.hosted_plan_name_uid <> ALL ('{3,4,5,6,7,10,11}'::integer[])) OR (gitlab_subscription_histories.hosted_plan_name_uid IS NULL) OR (gitlab_subscription_histories.trial AND (gitlab_subscription_histories.hosted_plan_name_uid <> 10)))
Rows Removed by Filter: 5
Buffers: shared hit=5 read=3
I/O Timings: read=0.120 write=0.000References
- Proposal and discussion: https://gitlab.com/gitlab-org/gitlab/-/work_items/632305
- Epic: https://gitlab.com/groups/gitlab-org/-/work_items/23455
- Outbound email rate limit this builds on: https://gitlab.com/gitlab-org/gitlab/-/work_items/627183
- Per-namespace override, the long-term replacement for flag opt-outs once the
wipflag is removed: https://gitlab.com/gitlab-org/gitlab/-/work_items/627337
Screenshots or screen recordings
New section in Admin > Settings > Network, shown only on GitLab.com when the flag is enabled globally. Screenshot to follow.
How to set up and validate locally
-
Simulate GitLab.com:
export GITLAB_SIMULATE_SAAS=1, then restart GDK. -
In the Rails console, enable the flag and make a group that has just upgraded to Premium:
Feature.enable(:service_desk_paid_namespace_probation) group = Group.find_by_full_path('your-group') group.gitlab_subscription.update!(hosted_plan_name_uid: GitlabSubscriptions::SystemDefined::Plan.find_by(name: 'premium').id, trial: false) ServiceDesk::PaidNamespaceProbation.new(group).active? # => true -
Opt the group out and check the probation is lifted (
Gitlab::SafeRequestStoreis off in the console, so there's nothing cached):Feature.opt_out(:service_desk_paid_namespace_probation, group) ServiceDesk::PaidNamespaceProbation.new(group).active? # => false -
Visit Admin > Settings > Network and expand Service Desk email limits for new paid namespaces. Change the number of days and save.
-
Disable the flag (
Feature.disable(:service_desk_paid_namespace_probation)) and check the section is gone.
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.