# Problem statement GitLab has documented "scale thresholds": * group membership counts * hierarchy depth * group-share combinations Beyond these thresholds, the platform becomes unreliable: slow dashboards, 500 errors, unresponsive instances, silent data access failures. We know these limits exist, but we're not enforcing them, we're not warning customers about them, and when customers hit them, we give them error messages that don't explain what's happened (or what to do next). In our [initial documentation](https://docs.google.com/document/d/1qiPGcsd4LMsS5W2RNM3mtOepK3X95rYkoCjWJBMjlu0/edit?tab=t.0#heading=h.uyo25e2mg5e1), we gave reference figures (1000 group members as a soft threshold, 1,500+ as the failure zone) which were based on incident reports and observation rather than verified benchmarks. This makes them hard to defend and harder to build policy around. Meanwhile, we have no visibility into how many customers are approaching these limits today: we only find out once they've already filed a support ticket. This epic takes us from "we know these things are problematic" to a state where limits are validated, communicated, and enforced. We'll also have tooling in place for customers who need to restructure their GitLab setup to stay within them. # Exit Criteria * Scale thresholds for group membership, hierarchy depth, and group-share combinations are validated against reproducible benchmarks, not just incident reports * Customers receive in-app warnings before hitting limits, not `500` errors afterwards * API and UI error responses for scale-related failures are actionable: they tell customers what happened and what to do next * Soft limits are configurable by instance administrators and enforced across all member addition paths (UI, API, LDAP sync, SAML provisioning) * Hard limits are enforced, with a supported self-service path for customers who need to restructure * No namespace on gitlab.com silently exceeds a hard limit without an admin-visible flag * Self-managed instances can raise limits within documented safe ranges via `application_settings` * We have dashboards that show the distribution of group sizes and hierarchy depths across gitlab.com so we can monitor the impact of enforcement and catch regressions ## Notes * Iterations 1 and 2 are **hard prerequisites**: we must validate thresholds, or we'll risk either being too conservative (annoying customers unnecessarily) or too lenient (not preventing real failures) * The [group-splitting tool](https://gitlab.com/gitlab-org/gitlab/-/work_items/599381) in Iteration 5 will likely be the most complex single issue here and should probably start as a spike in Iteration 4 so it doesn't gate the hard limit rollout * Self-managed customers need configurability at every stage: the defaults need to be safe, but removing flexibility entirely will generate a lot of noise ## DRI @rymai <!--STATUS NOTE START--> <!--STATUS NOTE END-->