The Ultimate Manual to GitLab Self-Hosted

Under GitLab Self-Managed, also known as On-perm, the customer is directly responsible for running the software. Everything from maintaining the network infrastructure to the operating system to database software is their responsibility. What’s more, the customer has to regularly maintain every aspect of the software to ensure it’s running properly, is secure, and is periodically updated to avoid any issues.

This Nira guide will take a detailed look into GitLab Self-Managed to help you understand how it works, how much it costs, and whether it’s a good fit for your business.

What is GitLab Self-Managed Anyway?

You’ve probably heard about GitLab by now.

It’s a well-rounded open-source DevOps platform that shortens the software delivery lifecycle to help teams automate software application release and delivery. In addition, the platform can streamline all manual processes and accelerate team velocity for best results.

Software developers also use GitLab as a version control system (VCS).

Now, there are two choices of deployments offered by GitLab: GitLab.com and GitLab Self-Managed. While the former is a Software-as-a-service (SaaS) offering, the latter is a privately hosted GitLab option.

If you want full control over your GitLab environment, you should consider downloading and installing GitLab Self-Managed on your own infrastructure or in the public cloud environment. Doing this will allow you to install, administer, and maintain your GitLab instance.

That said, you will need Linux experience to set up GitLab Self-Managed.

How GitLab Self-Managed Works

Generally, businesses with rigorous and elaborate security and compliance requirements choose GitLab Self-Managed because of the complete control they have over the Git host, including custom instance wide settings, auditing capabilities, unrestricted log access, and more.

In other words, you deploy your own GitLab instance on-premises or in the cloud and can enjoy GitLab almost anywhere, from Kubernetes to bare metal to VM. You also get custom Git hooks and plugins that allow you access to legacy tooling support and custom integrations.

Other features include large files (LFS), auditing, and searching, auditing logs and auditor uses, and advanced global and syntax searching, respectively.

Sounds like a good fit for your business? Great. You can get started in the GitLab Customers Portal, the place where you can manage your subscriptions and account details. In case you don’t have access to this portal, contact your reseller for any changes to the subscription.

Cloud Licensing

GitLab has a cloud licensing system to manage licenses for self-managed GitLab subscription plans. It includes:

Activation – Unlock plan features and activate self-managed instance through an activation code
Licensing – Sync subscription data between your self-managed instance and the GitLab platform

Cloud licensing includes handy features like auto-renewals, operational data to improve the product experience and provide proactive support, and quarterly subscription reconciliation.

How Cloud Licensing Works

You must follow a series of steps to enable cloud licensing, and in turn, GitLab Self-Managed. Here is a quick rundown.

Step 1: Activate Your License
After purchasing a GitLab Self-Managed plan, you will get an activation code sent to the email address associated with the Customers Portal account.

Open GitLab, and on the top bar, click Menu followed by Admin. Then on the left sidebar, select Subscription. Paste the activation code in the text field, and click Activate.

This page should display all the details of your subscription.

Step 2: License Sync
Once a day, a sync job will send license data to the Customers Portal through an encrypted HTTPS connection to customers.gitlab.com on port 443. This information will automate activation, provisioning, co-terms, and renewals, And runs daily around 3 AM UTC. In case the job fails, I’ll be retried up to 12 times over approximately 17 hours.

Keep in mind, this daily job will provide only the following information to the Customers Portal:

Date
Timestamp
License key
Historical maximum user count
Billable users count
GitLab version
Hostname
Instance ID
An MD5 hash of license

Step 3: Manually Sync Subscription Details
You have the flexibility to manually sync your subscription details at any time. To do this, you need to perform the following steps:

On the top menu bar, click Menu then Admin.
Select Subscription on the left sidebar.
In the Subscription details field, click Sync subscription details to confirm.

This will queue up a job. Once the job finishes, the subscription details will be updated automatically.

How to Get Started With GitLab Self-Managed

In this section, we’ll discuss how you can start your GitLab Self-Managed subscription under different heads.

Let’s get to it.

Part 1: Obtaining a Subscription

Here are the steps to subscribe to GitLab using a GitLab Self-Managed installation.

Open Customers Portal and buy a GitLab Self-Managed plan.
You’ll receive a license file sent to your registered email address. Upload this to your GitLab instance.

Part 2: Viewing Your Subscription

To see the status of your subscription, follow the steps below:

On the top menu bar, click Menu followed by Admin.
Select License on the left sidebar.

Note: You will need administrator privileges to view subscription status.

Part 3: Export Your License Usage

As an admin, you can export your license usage into a CSV. Here’s how to go about this:

Select Menu followed by Admin on the top bar.
On the left sidebar, click Subscription followed by Export license usage file on the top right-hand side.

With this file, you can manually process quarterly reconciliations or renewals. You can give GitLab this information if your instance is firewalled or air-gapped.

Generally, the License Usage CSV will contain the following information:

License key
Email
License start date
License end date
Company
Generated at (the timestamp for when the file was exported)
Table of historical user counts for each day in the period:
- Date the count was recorded
- Active user count

Part 4: Renew your Subscription

You can prepare for renewal by reviewing your account. Follow this up by renewing your GitLab Self-Managed subscription. Below, we’ve listed the steps to help you go about this.

#1: Renew Your Account for Subscription Renewal
You can renew or modify Customers Portal, but before you do anything, you should log in and verify or update your:

Invoice contact details on the Account details page
Cross-check the credit card on file on the Payment Methods page

In addition to the above, you should regularly review your user accounts. This is essential for two reasons:

Stale user accounts that aren’t blocked are counted as billable users. As a result, you may end up paying more than you should if you renew for too many users.
User accounts can be a security risk, which can be reduced through regular reviews.

#2: Add Seats to a Subscription
You can add seats to a subscription as required during the subscription period, increasing the license count. The cost of seats added during the subscription is prorated from the date of purchase through the subscription period termination.

Here are the steps to add seats to a subscription:

Log in to the Customers Portal, and then navigate to the Manage Purchases page.
Select Add more seats on the subscription card, and type in the number of additional users.
Click on Proceed to checkout.
Take a final look at the Subscription Upgrade Details, which will contain the total price for all users of the system and credit for what you’ve already paid. You will only be charged for the net change, so don’t worry about getting overcharged.
Finally, click on Confirm Upgrade.

After this, you will receive a payment receipt and a new license—both of which will be emailed to you. Upload your license to your instance to start using it.

#3: Renew Subscription
GitLab sends account administrators subscription renewal notifications 30 days before a subscription expires by displaying a banner in the GitLab user interface.

During renewal, GitLab recommends the following guidelines:

Block all inactive and unwanted users
Determine if you want to add more users to the upcoming subscription

Next, here’s how to renew your subscription:

Log into the Customers Portal, and click on the Renew button underneath your existing subscription.
In the first box, enter the total number of user licenses you will require for the subscription duration. Remember, this number should be at least equal to or greater than the number of billable users in the system at the time of account renewal.
In the second box, enter the number of users over the license for the user overage incurred in your previous subscription duration.
Cross-check your renewal details before completing the payment process.
You will find a license for the renewal term available for download on the Manage Purchases page. This should be there on the relevant subscription card. Once you locate it, select Copy license to clipboard. You can also get a copy of the license by selecting the Download license option.
Upload your new license to your instance on the platform.

That’s all you need to know about GitLab Self-Managed. We hope this guide helps you navigate the deployment easily, but if you have more questions about the facilities, check out this features comparison for a complete subscription review.