doc/administration/license_file.md
If you receive a license file from GitLab (for example, for a trial), you can
upload it to your instance or add it during installation. The license file is
a base64-encoded ASCII text file with a .gitlab-license extension.
The first time you sign in to your GitLab instance, a note with a link to the Add license page should be displayed.
Otherwise, add your license in the Admin area.
{{< history >}}
{{< /history >}}
To activate your subscription during installation, set the GITLAB_ACTIVATION_CODE environment variable with the activation code:
export GITLAB_ACTIVATION_CODE=your_activation_code
If you have a license, you can also import it when you install GitLab.
For self-compiled installations:
Place the Gitlab.gitlab-license file in the config/ directory.
To specify a custom location and filename for the license, set the
GITLAB_LICENSE_FILE environment variable with the path to the file:
export GITLAB_LICENSE_FILE="/path/to/license/file"
For Linux package installations:
Place the Gitlab.gitlab-license file in the /etc/gitlab/ directory.
To specify a custom location and filename for the license, add this entry to gitlab.rb:
gitlab_rails['initial_license_file'] = "/path/to/license/file"
For Helm Charts installations, use the global.gitlab.license configuration keys.
[!warning] These methods only add a license at the time of installation. To renew or upgrade a license, add the license in the Admin area in the web user interface.
If you use a license file or key to activate your instance in an offline environment, you are encouraged to submit your license
usage data monthly to simplify future purchases and renewals.
To submit the data, export your license usage
and send it by email to the renewals service, [email protected]. You must not open the license
usage file before you send it. Otherwise, the file's content could be manipulated by the used program (for example,
timestamps could be converted to another format) and cause failures when the file is being processed.
If you don't submit your data each month after your subscription start date, an email is sent to the address associated with your subscription and a banner displays to remind you to submit your data. The banner displays in the Admin area on the Dashboard and on the Subscription pages, and can be dismissed after the usage file has been downloaded. You can only dismiss it until the following month after you submit your license usage data.
Fifteen days before the license expires, a notification banner with the upcoming expiration date displays to GitLab administrators.
Licenses expire at the start of the expiration date, 00:00 server time.
When your license expires, GitLab locks features, like Git pushes and issue creation. Your instance becomes read-only, and an expiration message displays to all administrators.
For example, if a license has a start date of January 1, 2024 and an end date of January 1, 2025:
To remove the read-only state and resume functionality, renew your subscription.
If the license has been expired for more than 30 days, you must purchase a new subscription to resume functionality.
To go back to Free features, delete all expired licenses.
To remove a license from a GitLab Self-Managed instance:
Repeat these steps to remove all licenses, including those applied in the past.
To view your license details:
You can add and view more than one license, but only the latest license in the current date range is the active license.
When you add a future-dated license, it doesn't take effect until its applicable date. You can view all active subscriptions in the Subscription history table.
You can also export your license usage information to a CSV file.
The following commands can be run in the Rails console.
[!warning] Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case.
# License information (name, company, email address)
License.current.licensee
# Plan:
License.current.plan
# Uploaded:
License.current.created_at
# Started:
License.current.starts_at
# Expires at:
License.current.expires_at
# Is this a trial license?
License.current.trial?
# License ID for lookup on CustomersDot
License.current.license_id
# License data in Base64-encoded ASCII format
License.current.data
# Confirm the current billable seat count excluding guest users. This is useful for customers who use an Ultimate subscription tier where Guest seats are not counted.
User.active.without_bots.excluding_guests_and_requests.count
# Future license data follows the same format as current license data it just uses a different modifier for the License prefix
License.future_dated
Features listed in features.rb.
License.current.feature_available?(:jira_dev_panel_integration)
Features listed in features.rb.
p = Project.find_by_full_path('<group>/<project>')
p.feature_available?(:jira_dev_panel_integration)
key variablekey = "<key>"
license = License.new(data: key)
license.save
License.current # check to make sure it applied
license_file = File.open("/tmp/Gitlab.license")
key = license_file.read.gsub("\r\n", "\n").gsub(/\n+$/, '') + "\n"
license = License.new(data: key)
license.save
License.current # check to make sure it applied
These snippets can be saved to a file and executed using the Rails Runner so the license can be applied through shell automation scripts.
This is needed for example in a known edge-case with expired license and multiple LDAP servers.
To clean up the License History table:
TYPE = :trial?
# or :expired?
License.select(&TYPE).each(&:destroy!)
# or even License.all.each(&:destroy!)
You cannot add your license because there is no Subscription area. This issue might occur if:
GitLab displays a message prompting you to purchase additional users. This issue occurs if you add a license that does not have enough users to cover the number of users in your instance.
To fix this issue, purchase additional seats to cover those users. For more information, read the licensing FAQ.
In GitLab 14.2 and later, for instances that use a license file, the following rules apply:
For example, if you purchase a license for 100 users, you can have 110 users when you add your license. However, if you have 111 users, you must purchase more users before you can add the license.
Start GitLab Ultimate trial still displays after adding licenseTo fix this issue, restart Puma or your entire GitLab instance.