Skip to content
Snippets Groups Projects

GitLab Self-Managed subscription

  • Tier: Premium, Ultimate
  • Offering: GitLab Self-Managed

After you subscribe to GitLab, you can manage the details of your self-managed subscription. If you experience any issues, see the troubleshooting page.

How GitLab bills for users

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.

Billable users

Billable users count toward the number of subscription seats purchased in your subscription.

The number of billable users changes when you block, deactivate, or add users to your instance during your current subscription period.

A user is not counted as a billable user if:

The amount of Billable users is reported once a day in the Admin area.

Users in subscription

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.

Maximum users

The number of maximum users reflects the highest number of billable users on your system for the current license period.

Users over subscription

A GitLab subscription is valid for a specific number of seats. The number of users over subscription shows how many users are in excess of the number allowed by the subscription, in the current subscription period.

Calculated as Maximum users - Users in subscription for the current license term. For example, you purchase a subscription for 10 users.

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

Users over subscription = 13 - 10 (Maximum users - users in license)

The users over subscription value is always zero for trial license.

If users over subscription value is above zero, then you have more users in your GitLab instance than you are licensed for. You must pay for the additional users before or at the time of renewal. This is called the true up process. If you do not do this, your license key does not work.

To view the number of users over subscription, go to the Admin area.

Free Guest users

  • Tier: Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

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.

  • If your project is private or internal, a user with the Guest role has a set of permissions.
  • If your project is public, all users, including those with the Guest role can access your project.
  • A user's highest assigned role is updated asynchronously and may take some time to update.

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.

View users

View the lists of users in your instance:

  1. On the left sidebar, at the bottom, select Admin.
  2. Select Users.

Select a user to view their account information.

Check daily and historical billable users

Prerequisites:

  • You must be an administrator.

You can get a list of daily and historical billable users in your GitLab instance:

  1. Start a Rails console session.

  2. Count the number of users in the instance:

    User.billable.count
  3. Get the historical maximum number of users on the instance from the past year:

    ::HistoricalData.max_historical_user_count(from: 1.year.ago.beginning_of_day, to: Time.current.end_of_day)

Update daily and historical billable users

Prerequisites:

  • You must be an administrator.

You can trigger a manual update of the daily and historical billable users in your GitLab instance.

  1. Start a Rails console session.

  2. Force an update of the daily billable users:

    identifier = Analytics::UsageTrends::Measurement.identifiers[:billable_users]
    ::Analytics::UsageTrends::CounterJobWorker.new.perform(identifier, User.minimum(:id), User.maximum(:id), Time.zone.now)
  3. Force an update of the historical max billable users:

    ::HistoricalDataWorker.new.perform

Manage users and subscription seats

Managing the number of users against the number of subscription seats can be difficult:

  • 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 sign-up is turned on in your instance, anyone who can access the instance can sign up for an account.

GitLab has several features to help you manage the number of users. You can:

Buy seats for a subscription

To increase the number of users covered by your license, buy seats for your subscription 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.

You cannot buy seats for your subscription if either:

  • You purchased your subscription through an authorized reseller (including GCP and AWS marketplaces). Contact the reseller to add more seats.
  • You have a multi-year subscription. Contact the sales team to add more seats.

To buy seats for a subscription:

  1. Sign in to the Customers Portal.
  2. Go to the Subscriptions & purchases page.
  3. Select Add seats on the relevant subscription card.
  4. Enter the number of additional users.
  5. Review the Purchase summary section, which lists the total price for all users on the system and a credit for what you've already paid. You are only charged for the net change.
  6. Enter your payment information.
  7. Select Purchase seats.

A payment receipt is emailed to you, which you can also access in the Customers Portal under Invoices.

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.

Export your license usage

Prerequisites:

  • You must be an administrator.

You can export your license usage into a CSV file.

This file contains the information GitLab uses to manually process quarterly reconciliations or renewals. If your instance is firewalled or an offline environment, you must provide GitLab with this information.

Do not open the license usage file. If you open the file, failures might occur when you submit your license usage data.

  1. On the left sidebar, at the bottom, select Admin.
  2. Select Subscription.
  3. In the upper-right corner, select Export license usage file.

License usage file contents

The license usage file includes the following information:

  • License key
  • Licensee email
  • License start date (UTC)
  • License end date (UTC)
  • Company
  • Timestamp the file was generated at and exported (UTC)
  • Table of historical user counts for each day in the period:

A custom format is used for dates and times in CSV files.

Renew your subscription

You can renew your subscription automatically or manually.

You should renew your subscription manually if you want to either:

  • Renew for fewer seats.
  • Increase or decrease the quantities of products being renewed.
  • Remove add-on products no longer needed for the renewed subscription term.
  • Upgrade the subscription tier.

Before your subscription renewal date, you should review your account.

Contact the support team if you need help accessing the Customers Portal or changing the contact person who manages your subscription. Contact the sales team if you need help renewing your subscription.

Review your account

You should regularly review your billing account settings and purchasing information.

To review your billing account settings:

  1. Sign in to the Customers Portal.
  2. Select Billing account settings.
  3. Verify or update:
    • Under Payment methods, the credit card on file.
    • Under Company information, the subscription and billing contact details.
  4. Save any changes.

You should also regularly review your user accounts to make sure that you are only renewing for the correct number of active billable users. Inactive user accounts:

  • Might count as billable users. You pay more than you should if you renew inactive user accounts.
  • Can be a security risk. A regular review helps reduce this risk.

For more information, see the documentation on:

Renew for fewer seats

If you want to renew with fewer seats, you can do either of the following:

Renew subscription manually

15 days before a subscription expires, a banner with the subscription expiry date displays for administrators in the GitLab user interface.

You cannot manually renew your subscription more than 15 days before the subscription expires. To check when you can renew:

  1. Sign in to the Customers Portal.
  2. Select Subscription actions ({ellipsis_v}), then select Renew subscription to view the date you can renew.

To manually renew your subscription:

  1. Before the renewal date, block any inactive or unwanted users.

  2. Determine the number of users you need in the next subscription period.

  3. Sign in to the Customers Portal.

  4. Under your existing subscription, select Renew. This button does not display until 15 days before the subscription expires.

  5. If renewing Premium or Ultimate products, in the Seats text box, enter the total number of user seats you'll need for the upcoming year.

    Make sure this number is equal to, or greater than the number of billable users in the system at the time of renewal.

  6. Optional. If the maximum number of users in your instance exceeded the number you were licensed for in the previous subscription term, the overage is due when you renew.

    In the Users over license text box, enter the number of users over subscription for the user overage incurred.

  7. Optional. If renewing add-on products, review and update the desired quantity. You can also remove products.

  8. Optional. If upgrading the subscription tier, select the desired option.

  9. Review your renewal details and select Renew subscription to complete the payment process.

  10. On the Subscriptions & purchases page on the relevant subscription card, select Copy activation code to get a copy of the renewal term activation code.

  11. Add the activation code to your instance.

To add products to your subscription, contact the sales team.

Automatic subscription renewal

Prerequisites:

At least two days before your renewal date, you should review your account so that your changes synchronize to GitLab in time for your renewal.

When a subscription is set to automatically renew, it renews automatically at midnight UTC on the expiration date without a gap in available service. Subscriptions purchased through the Customers Portal are set to automatically renew by default.

The number of user seats is adjusted to fit the number of billable users in your instance at the time of renewal, if that number is higher than the current subscription quantity.

Email notifications

15 days before a subscription automatically renews, an email is sent with information about the renewal.

  • If your credit card is expired, the email tells you how to update it.
  • If you have any outstanding overages or your subscription is not able to automatically renew for any other reason, the email tells you to contact our Sales team or manually renew in the Customers Portal.
  • If there are no issues, the email specifies the:
    • Names and quantity of the products being renewed.
    • Total amount you owe. If your usage increases before renewal, this amount will change.

Enable or disable automatic subscription renewal

You can use the Customers Portal to enable or disable automatic subscription renewal:

  1. Sign in to the Customers Portal. You are taken to the Subscriptions & purchases page.
  2. Check the subscription card:
    • If the card displays Expires on DATE, your subscription is not set to automatically renew. To enable automatic renewal, in Subscription actions ({ellipsis_v}), select Turn on auto-renew.
    • If the card displays Auto-renews on DATE, your subscription is set to automatically renew. To disable automatic renewal:
      1. In Subscription actions ({ellipsis_v}), select Cancel subscription.
      2. Select a reason for cancelling.
      3. Optional: In Would you like to add anything?, enter any relevant information.
      4. Select Cancel subscription.

Manage renewal invoice

An invoice is generated for your renewal. To view or download this renewal invoice, go to the Customers Portal invoices page.

If your account has a saved credit card, the card is charged for the invoice amount.

If we are unable to process a payment or the auto-renewal fails for any other reason, you have 14 days to renew your subscription, after which your GitLab tier is downgraded.

Add or change the contacts for your subscription

Contacts can manage subscriptions and billing account settings.

For information about how to transfer ownership of the Customers Portal account to another person, see Change profile owner information.

To add another contact for your subscription, see Add a billing account manager.

Subscription expiry

Licenses expire at the start of the expiration date, 00:00 server time.

When your license expires, after a 14 day grace period:

  • Your instance becomes read-only.
  • GitLab locks features, such as Git pushes and issue creation.
  • An expiration message is displayed to all administrators.

For example, if a license has an expiry date of January 1, 2025:

  • It expires at 11:59:59 PM server time December 31, 2024.
  • It is considered expired from 12:00:00 AM server time January 1, 2025.
  • The grace period of 14 days starts at 12:00:00 AM server time January 1, 2025 and ends at 11:59:59 PM server time January 14, 2025.
  • Your instance becomes read-only at 12:00:00 AM server time January 15, 2025.

After your license has expired:

Storage

The amount of storage and transfer for GitLab Self-Managed instances has no application limits. Administrators are responsible for the underlying infrastructure costs and can set repository size limits.