Installing GitLab Runner on Ubuntu 20.04: A Comprehensive Guide

Setting up GitLab Runner on Ubuntu 20.04 can seem tricky, but it’s actually pretty simple if you follow the right steps. This guide will walk you through everything you need to know, from preparing your system to uninstalling GitLab Runner if you ever need to. Let’s get started!

Key Takeaways

• Updating your system and installing necessary dependencies is crucial before adding the GitLab Runner repository.
• Adding the official GitLab Runner repository ensures you get the latest versions and updates.
• Registering your GitLab Runner with your GitLab instance is essential for it to pick up jobs.
• Managing the GitLab Runner service includes starting, stopping, and enabling auto-start on boot.
• Uninstalling GitLab Runner involves stopping the service, removing the package, and cleaning up residual files.

Preparing Your Ubuntu System

Updating Package Lists

Before diving into the installation of GitLab Runner, it’s essential to ensure your system’s package lists are up to date. Start by running the command sudo apt update to refresh your package database. This step fetches the latest versions of packages and their dependencies, setting the stage for a smooth installation process.

After updating the package lists, you might want to check for upgradable packages. Execute sudo apt list --upgradable to see a list of packages that can be updated. While upgrading your system isn’t mandatory for installing GitLab Runner, it’s a good practice to keep your system current with the latest security patches and improvements.

To apply updates, use sudo apt upgrade. This command will download and install available updates, which may include important security patches and enhancements for your system’s stability and performance.

Installing Required Dependencies

Next, you’ll need to install some necessary dependencies. These packages are crucial for the proper functioning of GitLab Runner. Run the following command to install them:

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

These dependencies include tools for secure communication, time zone data, and essential libraries. Ensuring these are installed will prevent issues during the GitLab Runner setup.

Adding GitLab Runner Repository

To install GitLab Runner, you need to add its repository to your system. This repository contains the latest version of GitLab Runner, ensuring you get the most up-to-date features and security patches. Use the following command to add the repository:

curl -sS https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash

This command downloads and runs a script that adds the GitLab Runner repository to your system. Once the repository is added, you can proceed with the installation of GitLab Runner.

Tip: Adding the repository ensures that you can easily update GitLab Runner in the future using standard package management commands.

Installing GitLab Runner

Downloading GitLab Runner Package

First, make sure your package lists are up-to-date. Run:

sudo apt-get update

Next, download the GitLab Runner package with this command:

sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64

After downloading, give the binary executable permissions:

sudo chmod +x /usr/local/bin/gitlab-runner

Ensure the binary is in a directory included in your system’s PATH for easy execution.

Running the Installation Command

With the package downloaded, install GitLab Runner by running:

sudo apt-get install gitlab-runner

This command will install the latest version of GitLab Runner on your system. If you need a specific version, use:

apt-cache madison gitlab-runner
sudo apt-get install gitlab-runner=<version>

Verifying Installation

To check if GitLab Runner is installed correctly, run:

sudo gitlab-runner --version

You should see output similar to this:

Version:      15.7.2
Git revision: 0e7679e6
Git branch:   15-7-stable
GO version:   go1.18.9
Built:        2023-01-13T23:55:39+0000
OS/Arch:      linux/amd64

To ensure the service is running, use:

sudo gitlab-runner status

You should see a message indicating the service is active and running.

Configuring GitLab Runner

Creating a GitLab CI/CD User

To keep your GitLab Runner secure, create a dedicated user for CI/CD tasks. Start by adding a new user with the adduser command. This user will handle all the CI/CD processes.

sudo adduser gitlab-runner

Next, grant the user the necessary permissions. If you’re using Docker, add the user to the Docker group. You might also need to configure sudo privileges for tasks that need admin access.

• Create the user: sudo adduser gitlab-runner
• Add to Docker group: sudo usermod -aG docker gitlab-runner
• Configure sudoers file for admin privileges

Ensure that the GitLab Runner user has the minimal permissions required to perform its duties. Over-privileged accounts can pose a security risk to your system.

Editing the Configuration File

After installing GitLab Runner, you need to edit the configuration file to match your project’s needs. The file is usually named config.toml and is located in /etc/gitlab-runner/.

Open the file with your preferred text editor. For example, using nano:

sudo nano /etc/gitlab-runner/config.toml

In this file, you can specify executor types like shell or Docker and configure their settings. If you’re using Docker, set up the Docker image and services the runner will use.

It’s crucial to test the runner after making changes to the configuration file to ensure that it operates as expected.

Setting Up the Runner Environment

After installing GitLab Runner, set up the environment to ensure smooth operation. Configure all necessary environment variables to match your project’s needs and your Ubuntu system specifics. This includes setting paths, defining network configurations, and customizing the runner’s behavior.

For GitLab Premium users, additional environment configurations may be available. Here are some common environment variables you might need to set:

• CI_SERVER_URL: The URL of your GitLab instance.
• RUNNER_EXECUTOR: The executor type, such as shell or docker.
• DOCKER_IMAGE: The default Docker image to use if you’re using the Docker executor.

Ensure that the network settings allow the runner to communicate with the GitLab server without interruptions.

Registering GitLab Runner with GitLab

Generating a Registration Token

To link your GitLab Runner with your GitLab instance, you need a registration token. This token is essential for authenticating your runner with the GitLab server. You can get this token from your project’s settings or, for group runners, from the group’s settings. For advanced users, GitLab’s API can also generate tokens programmatically.

Follow these steps to generate a registration token:

1. Go to your GitLab project or group settings.
2. Navigate to the CI/CD settings section.
3. Find the ‘Runners’ area.
4. Click on ‘Register a Runner’ to view the token.

Important: Store the registration token securely as it grants access to your GitLab CI/CD environment.

Running the Register Command

Once you have the token, the next step is to register your runner. Open a terminal on your runner machine and run the following command:

sudo gitlab-runner register

You will be prompted to enter the GitLab instance URL, the registration token, and a description for your runner. This command sets up the communication between your GitLab instance and the runner machine.

Troubleshooting Registration Issues

Sometimes, you might face issues during registration. Common problems include network issues, incorrect registration tokens, or configuration errors. Here’s how to troubleshoot:

• Verify the GitLab Runner installation by checking the service status.
• Ensure the registration token is valid and not expired.
• Double-check for typos in the registration command, especially the URL and token.
• Review the GitLab Runner logs for detailed error messages.

If you encounter a specific error, like a "500 Internal Server Error," search for the error code along with ‘GitLab Runner’ in online forums or the GitLab issue tracker.

Tip: Always keep your GitLab Runner updated to the latest version to avoid compatibility issues.

Managing GitLab Runner

Starting and Stopping the Service

Managing the GitLab Runner service is straightforward. To start the service, use the command:

sudo gitlab-runner start

To stop the service, use:

sudo gitlab-runner stop

And to restart the service, simply run:

sudo gitlab-runner restart

These commands ensure that your GitLab Runner is running when needed and stopped when not in use, saving system resources.

Enabling Auto-Start on Boot

To make sure your GitLab Runner starts automatically when your system boots up, you need to enable the service. Use the following command:

sudo systemctl enable gitlab-runner

This command configures your system to start the GitLab Runner service automatically at boot time, ensuring that your CI/CD pipelines are always ready to run.

Checking Runner Status

It’s important to regularly check the status of your GitLab Runner to ensure it’s running smoothly. You can do this with the command:

sudo gitlab-runner status

This will provide you with information about the current state of the service. Keeping an eye on the status helps you catch issues early and maintain continuous integration without interruptions.

Regularly monitoring your GitLab Runner ensures that your CI/CD processes run without a hitch, minimizing downtime and maximizing productivity.

Uninstalling GitLab Runner

If you need to remove GitLab Runner from your Ubuntu 20.04 system, follow these steps. This guide will help you cleanly uninstall the software and remove any residual files.

Stopping the GitLab Runner Service

First, you need to stop the GitLab Runner service. Open your terminal and type:

sudo gitlab-runner stop

This command will halt the service, ensuring no processes are running during the uninstallation.

Removing GitLab Runner Package

Next, remove the GitLab Runner package from your system. Use the following command:

sudo apt autoremove --purge gitlab-runner

This command will uninstall GitLab Runner and clean up any dependencies that were installed with it.

Cleaning Up Residual Files

Finally, delete any remaining files and directories associated with GitLab Runner. Run these commands one by one:

sudo rm -rf /etc/apt/sources.list.d/runner_gitlab-runner.list
sudo deluser --remove-home gitlab-runner
sudo rm -rf /etc/gitlab-runner

These commands will remove the repository list, delete the GitLab Runner user, and clean up the installation directory.

Note: Make sure to double-check the directories and files before deleting them to avoid removing any important data.

By following these steps, you can ensure that GitLab Runner is completely removed from your Ubuntu 20.04 system. Regular maintenance like this helps keep your system clean and efficient.

Frequently Asked Questions

What is GitLab Runner?

GitLab Runner is a tool that runs jobs in your GitLab CI/CD pipelines. It helps automate tasks like testing and deploying your code.

How do I update GitLab Runner on Ubuntu?

To update GitLab Runner, first stop the service with ‘sudo gitlab-runner stop’. Then download the latest version and replace the old one. Finally, restart the service using ‘sudo gitlab-runner start’.

What should I do if I get a ‘500 Internal Server Error’ while registering GitLab Runner?

A ‘500 Internal Server Error’ can happen for many reasons. Check your internet connection, ensure your GitLab instance is running, and try again. If the problem persists, consult the GitLab documentation or community forums.

How can I uninstall GitLab Runner from my Ubuntu system?

To uninstall GitLab Runner, stop the service with ‘sudo gitlab-runner stop’. Then remove the package using ‘sudo apt purge –autoremove gitlab-runner’. Finally, delete any leftover files and directories.

Why is my GitLab Runner not picking up jobs?

If your GitLab Runner isn’t picking up jobs, ensure it’s properly registered and running. Check the tags assigned to your jobs and runner, and make sure they match.

How do I register a GitLab Runner with my GitLab instance?

To register a GitLab Runner, get a registration token from your GitLab project settings. Then run ‘sudo gitlab-runner register’ and follow the instructions, providing the token and other required details.