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_email or CC). Emails on Push and pipeline emails keep their plan limits.
    • Gitlab::Email::NamespaceRateLimiter gets an optional plan_limits: callable, defaulting to the namespace's plan limits. It's only called once limiting is enabled, so the probation lookup never runs while service_desk_email_rate_limit is off.
    • ServiceDesk::EmailRateLimiter passes its own plan_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_probation feature flag is enabled for the root namespace.
    • It became paid less than service_desk_paid_namespace_probation_days ago.
  • When "became paid" happened. This is read from gitlab_subscription_histories, not from start_date, because start_date moves 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_out in the Features API). GitLab's Feature wrapper honours actor opt-outs even when a flag is enabled globally.
  • Admin setting. service_desk_paid_namespace_probation_days is stored in the existing rate_limits JSONB column, so no migration is needed. 0 disables 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_subscriptions SaaS 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 1

The 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.000

A 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.000

A 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.000

The 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.000

References

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

  1. Simulate GitLab.com: export GITLAB_SIMULATE_SAAS=1, then restart GDK.

  2. 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
  3. Opt the group out and check the probation is lifted (Gitlab::SafeRequestStore is off in the console, so there's nothing cached):

    Feature.opt_out(:service_desk_paid_namespace_probation, group)
    ServiceDesk::PaidNamespaceProbation.new(group).active? # => false
  4. Visit Admin > Settings > Network and expand Service Desk email limits for new paid namespaces. Change the number of days and save.

  5. 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.

Edited by Mario Celi

Merge request reports

Loading
Loading