Skip to content
W3S101

GitLab - Installation

GitLab - Understanding GitLab and Runner Installation

Section titled “GitLab - Understanding GitLab and Runner Installation”

GitLab is a comprehensive DevOps platform, delivered as a single application. It provides Git repository management, issue tracking, CI/CD pipelines, and much more. You can use GitLab.com (SaaS offering, no installation required for the platform itself) or host your own self-managed GitLab instance.

GitLab Runners are agents that execute your CI/CD jobs. Runners can be installed separately from the GitLab instance and can be set up on various operating systems and environments (physical servers, virtual machines, Docker containers, Kubernetes clusters).

This chapter covers:

  • Installing and registering a GitLab Runner on Windows.
  • Installing a self-managed GitLab instance (Omnibus package) on Ubuntu.

Before installing either, ensure you have Git installed on the machine where the Runner or GitLab instance will operate. Git is a version control system crucial for interacting with GitLab repositories. You can download Git from git-scm.com.

Installing and Registering GitLab Runner on Windows

Section titled “Installing and Registering GitLab Runner on Windows”

Follow these steps to install and register a GitLab Runner on a Windows system, which can then pick up CI/CD jobs from your GitLab instance (GitLab.com or self-managed).

Step 1: Create a folder for the GitLab Runner. For example, C:\GitLab-Runner.

Step 2: Download the GitLab Runner binary for Windows. Go to the official GitLab Runner installation documentation (Install GitLab Runner on Windows) to find the link for the latest amd64 or x86 binary. Download it and place it into the folder you created (e.g., C:\GitLab-Runner). Rename the downloaded executable to gitlab-runner.exe.

Step 3: Open PowerShell or Command Prompt as Administrator. Navigate to the folder where you placed gitlab-runner.exe.

cd C:\GitLab-Runner

Step 4: Register the Runner. This command will prompt you for several pieces of information:

.\gitlab-runner.exe register

Step 5: Enter the GitLab instance URL. This is the URL of your GitLab instance (e.g., https://gitlab.com/ if you are using GitLab.com, or http://your-gitlab.example.com/ for a self-managed instance).

Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/):
https://gitlab.com

Step 6: Enter the registration token. To get this token:

  • Navigate to your project or group in GitLab.
  • Go to ‘Settings’ > ‘CI/CD’.
  • Expand the ‘Runners’ section.
  • You will find specific registration tokens for shared runners (if available/enabled by admins), group runners, or project runners. Copy the appropriate token.
Please enter the registration token:
<your_copied_token_here>

Step 7: Enter a description for the Runner. This helps you identify it in the GitLab UI.

Please enter a description for the runner:
[Windows-PC]: My Windows Shell Runner

Step 8: Enter tags for the Runner. Tags are used to direct specific jobs to specific runners (e.g., windows,build,dotnet). Separate tags with commas.

Please enter tags for the runner (comma-separated):
windows,shell

Step 9 (Optional): Enter an optional maintenance note for the Runner.

Please enter optional maintenance note for the runner:
Maintained by CI Team

Step 10: Choose an executor. The executor determines how CI/CD jobs will be run. Common choices include:

  • shell: Runs jobs directly on the machine where the runner is installed. Simple but less isolated.
  • docker: Uses Docker containers to run jobs, providing a clean, isolated environment. Requires Docker to be installed.
  • docker-windows: Similar to docker, but for Windows containers.
  • virtualbox, parallels: Use virtual machines.
  • kubernetes: Deploys jobs to a Kubernetes cluster.
Please enter the executor: shell, docker, docker-windows, kubernetes, virtualbox, custom ...
shell

If you chose docker or docker-windows, you’ll be asked for a default Docker image (e.g., alpine:latest or mcr.microsoft.com/dotnet/sdk:6.0).

Once registration is complete, a config.toml file will be created in C:\GitLab-Runner with the runner’s configuration.

Step 11: Install the GitLab Runner as a service and start it.

.\gitlab-runner.exe install
.\gitlab-runner.exe start

You can verify that the runner is active by checking the ‘Runners’ section in your GitLab project/group settings. It should appear in the list of available runners.

The config.toml file (usually at C:\GitLab-Runner\config.toml) stores the runner’s configuration. You can edit this file for advanced settings.

Installing GitLab (Self-Managed) on Ubuntu

Section titled “Installing GitLab (Self-Managed) on Ubuntu”

The recommended way to install GitLab on Ubuntu (and other supported Linux distributions) is using the Omnibus package. This package bundles all necessary services and components.

Important: Always refer to the official GitLab installation documentation for the most up-to-date instructions and system requirements, as these can change.

The general steps are as follows (example for Ubuntu):

Step 1: Update your server and install dependencies. Log in to your Ubuntu server via SSH.

sudo apt-get update
sudo apt-get install -y curl openssh-server ca-certificates tzdata postfix

During Postfix installation, select ‘Internet Site’ and enter your server’s domain name for mail configuration.

Step 2: Add the GitLab package repository and install GitLab. Visit the official GitLab installation page, select your Linux distribution (e.g., Ubuntu), and follow the script provided to add the repository. Then, install the GitLab package (e.g., gitlab-ce for Community Edition or gitlab-ee for Enterprise Edition).

The script usually looks like this (VERIFY ON OFFICIAL SITE FIRST!):

curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
sudo EXTERNAL_URL="http://gitlab.example.com" apt-get install gitlab-ce

Replace http://gitlab.example.com with the URL you want to use to access your GitLab instance. If you plan to use HTTPS (recommended), configure it after initial setup or use https://gitlab.example.com if you have SSL certificates ready. This EXTERNAL_URL is crucial.

Step 3: GitLab will install and configure itself. This process can take several minutes.

Step 4: Once the installation is complete, open a web browser and navigate to the EXTERNAL_URL you configured. On your first visit, GitLab will prompt you to set up an administrative password for the initial root user.

Step 5: After setting the password, you can log in as root with the password you just created.

Managing Your GitLab Instance

Section titled “Managing Your GitLab Instance”

GitLab provides a command-line tool gitlab-ctl for managing your instance:

  • sudo gitlab-ctl reconfigure: Applies any changes made to the main configuration file (/etc/gitlab/gitlab.rb).
  • sudo gitlab-ctl status: Shows the status of all GitLab components.
  • sudo gitlab-ctl start/stop/restart: Controls all GitLab services or specific ones (e.g., sudo gitlab-ctl restart nginx).

The main configuration file is /etc/gitlab/gitlab.rb. After modifying this file, always run sudo gitlab-ctl reconfigure.

Further Resources

Section titled “Further Resources”

Remember that self-managing GitLab requires ongoing maintenance, including updates, backups, and monitoring.