How To Configure GitLab Runners?

GitLab Runners are the backbone of GitLab’s Continuous Integration (CI) and Continuous Deployment (CD) pipelines. They are the agents responsible for executing the CI/CD jobs that automate the building, testing, and deployment of code changes.

In this article, we will guide you through the process of configuring GitLab Runners to suit your project’s needs.

What is a GitLab Runner?

A GitLab Runner is an application that works with GitLab CI/CD to run jobs in a pipeline. When a pipeline is triggered by a code push or a merge request, GitLab sends the jobs to the runner, which executes the defined tasks. Runners can be used to execute jobs on different types of infrastructure, including local machines, cloud servers, virtual machines, or Docker containers.

GitLab Runners can be categorized into:

• Shared Runners: These runners are provided by GitLab and are shared across all projects on GitLab.com. They are ideal for quick and simple jobs, but their performance may be inconsistent due to shared resources.
• Specific Runners: These runners are dedicated to a particular project or group of projects. They are typically installed and maintained by the project team, allowing for more control over the environment and resources.

Why Configure GitLab Runners?

Configuring your own GitLab Runners gives you more control over the infrastructure used to run your pipelines, leading to better performance, faster job execution, and greater flexibility. You can also choose the type of runner that best suits your project, whether it's a virtual machine, a Docker container, or even a bare-metal server.

Additionally, configuring GitLab Runners allows you to:

• Scale runners according to the project's needs.
• Run jobs on specific operating systems or hardware.
• Integrate with cloud platforms for dynamic scaling.
• Apply custom security configurations.

Steps To Configuring GitLab Runners

Step 1: Install GitLab Runner

The first step to configuring a GitLab Runner is to install it on the machine where it will run the jobs.

1. Choose Your Environment: Determine where you want to install the GitLab Runner. It can be on a local server, virtual machine, cloud instance, or even within a Docker container. For the purpose of this guide, we’ll assume you are installing it on a Linux server.
2. Download the GitLab Runner Binary: For Linux, run the following commands to download and install the GitLab Runner binary:

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

3. Install GitLab Runner as a Service: You can install the GitLab Runner as a service so that it starts automatically on system boot:

   sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
   sudo gitlab-runner start

Step 2: Register GitLab Runner

Once the GitLab Runner is installed, it needs to be registered with your GitLab instance or project.

1. Get Your Registration Token: Go to your GitLab project’s Settings > CI/CD > Runners section. Here, you’ll find a registration token that you’ll use to register the runner.
2. Register the Runner: Run the following command on the machine where GitLab Runner is installed:

   sudo gitlab-runner register

3. Enter the Required Information: The registration process will prompt you for the following information:
   • GitLab instance URL: This is the URL of your GitLab instance (e.g., https://gitlab.com for GitLab.com or your self-hosted GitLab instance URL).
   • Registration token: Enter the registration token you copied from the GitLab project.
   • Description: Give a brief description of the runner (e.g., "Project Build Runner").
   • Tags: These are optional tags you can use to assign jobs to specific runners.
   • Executor: Choose the executor that your runner will use. Common options include docker, shell, virtualbox, and ssh.
4. Choose Executor Type: Depending on your project’s needs, select the executor:
   • Docker: Ideal for isolated environments where jobs run inside Docker containers.
   • Shell: Executes jobs directly on the host machine’s shell.
   • VirtualBox/SSH: Runs jobs on remote machines via VirtualBox or SSH, which is useful for complex setups.
   For example, if you select docker, you’ll be prompted to specify the default Docker image to use for the jobs.

Step 3: Configure the Runner

After registration, you can further configure the runner by modifying the config.toml file located in /etc/gitlab-runner/.

Here’s an example of a basic config.toml file for a Docker-based runner:

[[runners]]
  name = "docker-runner"
  url = "https://gitlab.com/"
  token = "your-token"
  executor = "docker"
  [runners.custom_build_dir]
  [runners.docker]
    tls_verify = false
    image = "docker:latest"
    privileged = true
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]

• executor = "docker": This specifies that the runner will use Docker to run jobs.
• image = "docker:latest": This sets the default Docker image for jobs. You can override this in the .gitlab-ci.yml file.
• privileged = true: This allows the runner to execute privileged tasks inside Docker containers.

Step 4: Run and Manage the Runner

After configuring the runner, it should be ready to execute CI/CD jobs. To check the runner's status or restart it, you can use the following commands:

• Check Status:

  sudo gitlab-runner status

• Restart Runner:

  sudo gitlab-runner restart

Step 5: Test Your Runner

To ensure your GitLab Runner is properly configured, test it with a simple pipeline.

1. Create a .gitlab-ci.yml File: This file defines the CI/CD pipeline jobs. Create a .gitlab-ci.yml file in the root of your GitLab repository with the following content:

   stages:
       - build
   
   build_job:
       stage: build
       script:
           - echo "Running a build job"

2. Commit and Push: Commit and push the .gitlab-ci.yml file to trigger the pipeline. The GitLab Runner should pick up the job and execute it according to the instructions in the .gitlab-ci.yml file.

Step 6: Advanced Configuration and Scaling

If your project has larger or more complex requirements, you might want to configure multiple runners or scale them dynamically:

• Multiple Runners: You can configure multiple runners for different types of jobs (e.g., runners dedicated to building, testing, or deploying). Each runner can be tagged, and jobs can be assigned based on those tags.
• Autoscaling with Docker Machine: If you’re using cloud infrastructure, GitLab Runners can be configured to autoscale using docker-machine. This allows you to automatically spin up and down instances based on the workload.
• Caching: Use caching to store dependencies between pipeline runs and reduce build times. You can configure caching in the .gitlab-ci.yml file and the runner's config.toml.

Step 7: Security Considerations

When configuring GitLab Runners, especially in a shared or production environment, be mindful of security:

• Limit Access: Use tags to restrict jobs to specific runners, ensuring that only trusted projects can use critical infrastructure.
• Use Privileged Mode Carefully: Privileged mode in Docker runners allows for escalated privileges, which can be a security risk. Only enable it when necessary.
• Isolate Runners: Run GitLab Runners on isolated machines or environments to prevent interference with other services on the host.