doc/subscriptions/manage_seats.md
{{< details >}}
{{< /details >}}
Seat management is the process of controlling and monitoring which users occupy seats in your subscription. Effective seat management helps you control costs, prevent unexpected overage charges, and ensure your team members have the access they need.
Billable users are users who occupy seats in a subscription and count toward the number of seats purchased in your subscription.
The following users count as billable:
read_code permissionThe number of billable users changes when you block, deactivate, or add users to your instance or group during your current subscription period. If a user is in multiple groups or projects that belong to the same top-level group that holds the subscription, they are counted only once.
Seat usage is reviewed quarterly or annually.
To prevent overage fees from unintended user additions, you should:
A user is not counted as a billable user if:
When the number of billable users in your instance or top-level group exceeds the number of seats you've purchased, you have users over subscription (or seats owed).
This can happen, for example, when new users are added to your instance or group, or existing users are promoted to billable roles.
The number of users over subscription is calculated as: maximum users during billing period - purchased seats in your subscription.
For example, you purchase a subscription for 10 seats, and during the billing period the number of users varies as follows:
| Event | Billable users | Maximum users |
|---|---|---|
| Ten users occupy all 10 seats. | 10 | 10 |
| Two new users join. | 12 | 12 |
| Three users leave and their accounts are blocked. | 9 | 12 |
| Four new users join. | 13 | 13 |
In this case, you have 3 users over subscription (13 maximum users - 10 purchased seats).
When you exceed your subscription limit, you must pay for the additional users before or at the time of renewal. The cost is based on the maximum number of users during the billing period, not the current number of users.
On GitLab Self-Managed, for trial licenses the users over subscription value is always zero.
To avoid unexpected overage charges, you can:
{{< details >}}
{{< /details >}}
In the Ultimate tier, users who are assigned the Guest role do not consume a seat. The user must not be assigned any other role, anywhere in the instance for GitLab Self-Managed or in the namespace for GitLab.com.
On GitLab Self-Managed in the Premium tier, if a Guest user has a higher role in any project or group (including their personal namespace), when you upgrade to the Ultimate tier that higher role takes precedence and they will consume a seat. To ensure that Guest users on GitLab Self-Managed Ultimate will not consume a seat, confirm that they have no other role assignments in the instance or namespace before upgrading.
[!note] On GitLab Self-Managed, if a user creates a project, they are assigned the Maintainer or Owner role. To prevent a user from creating projects, as an administrator, you can mark the user as external.
Seat controls help you manage how users are added to your subscription and prevent unexpected overage fees. Seat controls apply to the instance on GitLab Self-Managed, and to the top-level group on GitLab.com.
{{< history >}}
saas_user_caps removed.{{< /history >}}
The user cap is the maximum number of billable users who can be added to a top-level group on GitLab.com, or create accounts on GitLab Self-Managed. After the user cap is reached, a group Owner or administrator must approve the users to be added to a top-level group or create accounts. After the users have been approved, they can access the group or instance. If a group Owner or an administrator increases or removes the user cap, users pending approval are automatically approved.
You can set a user cap for a top-level group and for an instance.
[!note] On GitLab.com, the user cap cannot be enabled if any group, subgroup, or project within the top-level group is shared outside of that namespace hierarchy. While the user cap is enabled, inviting groups outside the group hierarchy is prevented automatically and cannot be turned off. Inviting groups within the group and its subgroups is unaffected.
The number of billable users is updated once a day.
The user cap might take effect only after it has already been exceeded.
If the cap is set to a value below the current number of billable users (for example, 1), the cap is enabled immediately.
[!note] On GitLab Self-Managed, for instances that use LDAP or OmniAuth, when administrator approval for new user accounts is enabled or disabled, downtime might occur due to changes in the Rails configuration. You can set a user cap to enforce approvals for new users.
On GitLab.com Ultimate, you cannot add Guest users to a group when billable users exceed the user cap. For example, you set the user cap to five when you have three Developers and two Guests. After you add two more Developers, you cannot add any more users, even if they are Guest users who don't consume billable seats. For more information, see issue 441504.
{{< history >}}
auto_enable_restricted_access_on_self_managed. Enabled by default.{{< /history >}}
Restricted access blocks new billable users from being added when no licensed seats remain in your subscription. Enabling restricted access on a group or instance that is already over its seat limit does not change the role of, block, or remove any existing members; it prevents new billable additions while leaving current members untouched. Users who don't need access to projects or groups, such as those authenticating through GitLab as an OIDC provider, can be assigned the non-billable Minimal Access role to not be blocked by seat limits.
You can set restricted access for a top-level group and for an instance.
Restricted access is incompatible with external group sharing. When you turn on restricted access on GitLab .com, the setting to prevent inviting groups outside the group hierarchy is automatically turned on. This setting prevents overage fees caused by unintended billable users.
You can still independently configure project sharing for the group and its subgroups as needed.
Restricted access and user cap cannot be used together. Enabling restricted access disables user cap.
On GitLab Self-Managed, GitLab turns on restricted access automatically when your subscription does not allow overages. You cannot turn off restricted access when your subscription does not allow overages.
{{< history >}}
bso_minimal_access_fallback. Disabled by default.{{< /history >}}
When restricted access is enabled and no subscription seats are available, users provisioned through SAML, SCIM, or LDAP are assigned the Minimal Access role instead of their configured access level. This behavior ensures that synchronization can continue without consuming billable seats on GitLab.com and Self-Managed Ultimate.
Users with the Minimal Access role can authenticate and access the group, but have limited permissions. When seats become available, they can be promoted to their intended access level. Existing users with billable roles are not affected by this behavior.
You can view seat usage and manage users with Minimal Access.
When you turn on restricted access, the following known issues might occur and result in overages:
Additionally, restricted access might block the standard non-overage flows:
When restricted access is active and no licensed seats are available, dormant users (including enterprise users) who attempt to sign back in are set to pending approval instead of being reactivated. Their existing group and project memberships are preserved. Non-enterprise dormant members have their group membership removed instead of being deactivated. When they rejoin through SAML, SCIM, or LDAP sync, provisioning behavior applies and they receive the Minimal Access role if no seats are available.
A group Owner or an administrator can approve the users when seats become available.
Users with only the Minimal Access role are reactivated directly, because they do not consume a billable seat.
You can automatically remove dormant members.
On GitLab.com, when you change from user cap to restricted access, all pending members (both members awaiting approval and invited members) are automatically removed. To ensure users are approved as members, you must approve or remove pending members before enabling restricted access.
On GitLab Self-Managed, the user cap holds new user accounts pending admin approval, instead of blocking group or project members as on GitLab.com. When you change from user cap to restricted access, pending new user accounts are not automatically removed. The users remain blocked until an administrator approves them.
After you turn on restricted access, it governs whether a pending user approval can proceed:
{{< details >}}
{{< /details >}}
Your subscription cost is based on the maximum number of seats you use during the billing period.
If restricted access is:
You cannot buy seats for your subscription if either:
To buy seats for a subscription:
You receive the payment receipt by email. You can also access the receipt in the Customers Portal under Invoices.
You can reduce seats only during subscription renewal. If you want to reduce the number of seats in your subscription, you can renew for fewer seats.
{{< details >}}
{{< /details >}}
A GitLab Self-Managed subscription uses a hybrid model. You pay for a subscription according to the maximum number of users enabled during the subscription period.
For instances that are not offline or on a closed network, the maximum number of simultaneous users in the GitLab Self-Managed instance is checked each quarter.
If an instance is unable to generate a quarterly usage report, the existing true up model is used. Prorated charges are not possible without a quarterly usage report.
The number of users in subscription represents the number of users included in your current license, based on what you've paid for. This number remains the same throughout your subscription period unless you purchase more seats.
The number of maximum users reflects the highest number of billable users on your system for the current license period.
You can view and manage your billable users and license usage.
To increase the number of users covered by your license, buy more seats during the subscription period. The cost of seats added during the subscription period is prorated from the date of purchase through to the end of the subscription period. You can continue to add users even if you reach the number of users in license count. GitLab bills you for the overage.
If your subscription was activated with an activation code, the additional seats are reflected in your instance immediately. If you're using a license file, you receive an updated file. To add the seats, add the license file to your instance.
If LDAP is integrated with GitLab, anyone in the configured domain can sign up for a GitLab account. This can result in an unexpected bill at time of renewal. If new user accounts are allowed on your instance, anyone who can access the instance can sign up for an account.
To prevent unexpected overages, see the best practices for seat management.
{{< details >}}
{{< /details >}}
A GitLab.com subscription uses a concurrent (seat) model. You choose a number of seats for users who can use the subscription at the same time, and pay for a subscription according to the maximum number of users assigned to the top-level group, its subgroups and projects during the billing period.
You can add and remove users during the subscription period without incurring additional charges, as long as the total number of users at any given time doesn't exceed the number of seats in the subscription. If you add more users and exceed the number of purchased seats, you incur an overage, which will be included in your next invoice.
{{< history >}}
seat_flag_alerts.seat_flag_alerts removed.{{< /history >}}
If you have the Owner role for a top-level group that is linked to a subscription enrolled in quarterly subscription reconciliations, you receive alerts about the seat usage in the subscription.
The alert displays on group, subgroup, and project pages. After you dismiss the alert, it doesn't display again until another seat is used.
The alert displays at the following intervals:
| Seats in subscription | Alert |
|---|---|
| 0-15 | One seat remains. |
| 16-25 | Two seats remain. |
| 26-99 | 10% of seats remain. |
| 100-999 | 8% of seats remain. |
| 1000+ | 5% of seats remain. |
To view a list of seats being used:
For each user, a list shows groups and projects where the user is a direct member.
The data in seat usage listing, Seats in use, and Seats in subscription are updated live. The counts for Max seats used and Seats owed are updated once per day.
To view your subscription information and a summary of seat counts:
You can view the users that use seats on your subscription. To search for a user's seat usage:
The search returns a list of users whose first name, last name, or username match the search string.
For example, for a user with the first name Amir,
the search string ami results in a match, but amr does not.
To export seat usage data as a CSV file:
Prerequisites:
To export seat usage history as a CSV file:
The generated list contains all seats being used, and is not affected by the current search.
To remove a billable user from your GitLab.com subscription:
If you add a member to a group by sharing the group with another group, you can't remove the member by using this method. Instead, you can either:
{{< details >}}
{{< /details >}}
GitLab Enterprise Agile Planning is an add-on that helps bring non-engineering users into the same DevSecOps platform where engineers build, test, secure, and deploy code. The add-on enables cross-team collaboration between developers and non-developers without having to purchase GitLab Ultimate licenses for non-engineering team members.
With Enterprise Agile Planning seats, non-engineering team members can participate in planning workflows, measure software delivery velocity and impact with Value Stream Analytics, and use executive dashboards to drive organizational visibility.
For more information about Enterprise Agile Planning seats and how to purchase them, contact your GitLab sales representative.
A user occupies an Enterprise Agile Planning seat if:
A user occupies an Ultimate seat instead of an Enterprise Agile Planning seat if either:
To use your purchased Enterprise Agile Planning seats, you must first assign the Planner role to users in the group or project.
To prevent users with the Planner role from being assigned a different role and consequently consume Ultimate seats, you can use global SAML group membership lock.
You can view the number of Enterprise Agile Planning seats used in your subscription details and in Customers Portal. On GitLab Self-Managed, you can also view the total number of users by role in user statistics.
To effectively manage your subscription seats and control costs, follow these best practices.
Initial setup:
Regular activities:
Strategic planning: