Skip to content

GitLab self-managed subscription

DETAILS: Tier: Premium, Ultimate Offering: 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.

Obtain a self-managed subscription

To subscribe to GitLab for a GitLab self-managed installation:

  1. Go to the Pricing page and select a self-managed plan. You are redirected to the Customers Portal to complete your purchase.
  2. After purchase, an activation code is sent to the email address associated with the Customers Portal account. You must add this code to your GitLab instance.

NOTE: If you're purchasing a subscription for an existing Free GitLab self-managed instance, ensure you're purchasing enough seats to cover your users.

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 installation 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 license

The number of users you've paid for in the current license loaded on the system. The number does not change unless you add seats during your current subscription period.

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

DETAILS: Tier: Ultimate Offering: GitLab.com, 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.

NOTE: 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:

Add seats to a subscription

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

To add seats to 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.

If you purchased your subscription through an authorized reseller (including GCP and AWS marketplaces), contact the reseller to add more seats.

Subscription data synchronization

Prerequisites:

  • GitLab Enterprise Edition (EE).
  • Connection to the internet, and must not have an offline environment.
  • Activated your instance with an activation code.

Your subscription data is automatically synchronized once a day between your self-managed instance and GitLab.

At approximately 3:00 AM (UTC), this daily synchronization job sends subscription data to the Customers Portal. For this reason, updates and renewals might not apply immediately.

The data is sent securely through an encrypted HTTPS connection to customers.gitlab.com on port 443. If the job fails, it retries up to 12 times over approximately 17 hours.

After you have set up automatic data synchronization, the following processes are also automated.

Manually synchronize subscription data

You can also manually synchronize subscription data at any time.

  1. On the left sidebar, at the bottom, select Admin.
  2. Select Subscription.
  3. In the Subscription details section, select Sync ({retry}).

A synchronization job is then queued. When the job finishes, the subscription details are updated.

Subscription data

The daily synchronization job sends the following information to the Customers Portal:

  • Date
  • Timestamp
  • License key, with the following encrypted within the key:
    • Company name
    • Licensee name
    • Licensee email
  • Historical maximum user count
  • Billable users count
  • GitLab version
  • Hostname
  • Instance ID

Additionally, we also send add-on metrics such as:

  • Add-on type
  • Purchased seats
  • Assigned seats

Example of a license sync request:

{
  "gitlab_version": "14.1.0-pre",
  "timestamp": "2021-06-14T12:00:09Z",
  "date": "2021-06-14",
  "license_key": "eyJkYXRhIjoiYlR2MFBPSEJPSnNOc1plbGtFRGZ6M
  Ex1mWWhyM1Y3NWFOU0Zj\nak1xTmtLZHU1YzJJUWJzZzVxT3FQRU1PXG5
  KRzErL2ZNd0JuKzBwZmQ3YnY4\nTkFrTDFsMFZyQi9NcG5DVEdkTXQyNT
  R3NlR0ZEc0MjBoTTVna2VORlVcbjAz\nbUgrNGl5N0NuenRhZlljd096R
  nUzd2JIWEZ3NzV2V2lqb3FuQ3RYZWppWVFU\neDdESkgwSUIybFJhZlxu
  Y2k0Mzl3RWlKYjltMkJoUzExeGIwWjN3Uk90ZGp1\nNXNNT3dtL0Vtc3l
  zWVowSHE3ekFILzBjZ2FXSXVQXG5ENWJwcHhOZzRlcFhr\neFg0K3d6Zk
  w3cHRQTTJMTGdGb2Vwai90S0VJL0ZleXhxTEhvaUc2NzVIbHRp\nVlRcb
  nYzY090bmhsdTMrc0VGZURJQ3VmcXFFUS9ISVBqUXRhL3ZTbW9SeUNh\n
  SjdDTkU4YVJnQTlBMEF5OFBiZlxuT0VORWY5WENQVkREdUMvTTVCb25Re
  ENv\nK0FrekFEWWJ6VGZLZ1dBRjgzUXhyelJWUVJGTTErWm9TeTQ4XG5V
  aWdXV0d4\nQ2graGtoSXQ1eXdTaUFaQzBtZGd2aG1YMnl1KzltcU9WMUx
  RWXE4a2VSOHVn\nV3BMN1VFNThcbnMvU3BtTk1JZk5YUHhOSmFlVHZqUz
  lXdjlqMVZ6ODFQQnFx\nL1phaTd6MFBpdG5NREFOVnpPK3h4TE5CQ1xub
  GtacHNRdUxTZmtWWEZVUnB3\nWTZtWGdhWE5GdXhURjFndWhyVDRlTE92
  bTR3bW1ac0pCQnBkVWJIRGNyXG5z\nUjVsTWJxZEVUTXJNRXNDdUlWVlZ
  CTnJZVTA2M2dHblc4eVNXZTc0enFUcW1V\nNDBrMUZpN3RTdzBaZjBcbm
  16UGNYV0RoelpkVk02cWR1dTl0Q1VqU05tWWlU\nOXlwRGZFaEhXZWhjb
  m50RzA5UWVjWEM5em52Y1BjU1xueFU0MDMvVml5R3du\nQXNMTHkyajN5
  b3hhTkJUSWpWQ1BMUjdGeThRSEVnNGdBd0x6RkRHVWg1M0Qz\nMHFRXG5
  5eWtXdHNHN3VBREdCNmhPODFJanNSZnEreDhyb2ZpVU5JVXo4NCtD\nem
  Z1V1Q0K1l1VndPTngyc1l0TU5cbi9WTzlaaVdPMFhtMkZzM2g1NlVXcGI
  y\nSUQzRnRlbW5vZHdLOWU4L0tiYWRESVRPQmgzQnIxbDNTS2tHN1xuQ3
  hpc29D\nNGh4UW5mUmJFSmVoQkh6eHV1dkY5aG11SUsyVmVDQm1zTXZCY
  nZQNGdDbHZL\ndUExWnBEREpDXG41eEhEclFUd3E1clRYS2VuTjhkd3BU
  SnVLQXgvUjlQVGpy\ncHJLNEIzdGNMK0xIN2JKcmhDOTlabnAvLzZcblZ
  HbXk5SzJSZERIcXp3U2c3\nQjFwSmFPcFBFUHhOUFJxOUtnY2hVR0xWMF
  d0Rk9vPVxuIiwia2V5IjoiUURM\nNU5paUdoRlVwZzkwNC9lQWg5bFY0Q
  3pkc2tSQjBDeXJUbG1ZNDE2eEpPUzdM\nVXkrYXRhTFdpb0lTXG5sTWlR
  WEU3MVY4djFJaENnZHJGTzJsTUpHbUR5VHY0\ndWlSc1FobXZVWEhpL3h
  vb1J4bW9XbzlxK2Z1OGFcblB6anp1TExhTEdUQVdJ\nUDA5Z28zY3JCcz
  ZGOEVLV28xVzRGWWtUUVh2TzM0STlOSjVHR1RUeXkzVkRB\nc1xubUdRe
  jA2eCtNNkFBM1VxTUJLZXRMUXRuNUN2R3l3T1VkbUx0eXZNQ3JX\nSWVQ
  TElrZkJwZHhPOUN5Z1dCXG44UkpBdjRSQ1dkMlFhWVdKVmxUMllRTXc5\
  nL29LL2hFNWRQZ1pLdWEyVVZNRWMwRkNlZzg5UFZrQS9mdDVcbmlETWlh
  YUZz\nakRVTUl5SjZSQjlHT2ovZUdTRTU5NVBBMExKcFFiVzFvZz09XG4
  iLCJpdiI6\nImRGSjl0YXlZWit2OGlzbGgyS2ZxYWc9PVxuIn0=\n",
  "max_historical_user_count": 75,
  "billable_users_count": 75,
  "hostname": "gitlab.example.com",
  "instance_id": "9367590b-82ad-48cb-9da7-938134c29088",
  "add_on_metrics": [
    {
      "add_on_type": "duo_enterprise",
      "purchased_seats": 100,
      "assigned_seats": 50
    }
  ]
}

View your subscription

Prerequisites:

  • You must be an administrator.

You can view the status of your subscription:

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

The Subscription page includes the following information:

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.

WARNING: 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:

NOTE: 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:

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

Contact the support team if you need help accessing the Customers Portal, changing the contact person who manages your subscription, or 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. Under Upgrade your plan, select the subscription tier you want.

    You can upgrade your subscription tier, but you cannot change to a lower tier.

    To change to a lower tier, contact the GitLab sales team.

  6. Under Subscription details, in the Billable users text box, enter the total number of user seats you'll need for the upcoming year.

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

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

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

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

  10. Add the activation code to your instance.

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.

Upgrade your subscription tier

To upgrade your GitLab tier:

  1. Sign in to the Customers Portal.
  2. Select Upgrade plan on the relevant subscription card.
  3. Confirm the active form of payment, or add a new form of payment.
  4. Select the I accept the Privacy Statement and Terms of Service checkbox.
  5. Select Upgrade subscription.

The following is emailed to you:

  • A payment receipt. You can also access this information in the Customers Portal under Invoices.
  • A new activation code for your license.

The new tier takes effect on the next subscription sync, or you can synchronize your subscription manually to upgrade right away.

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 secondary contact.

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 self-managed instances has no application limits. Administrators are responsible for the underlying infrastructure costs and can set repository size limits.