GitLab Runner

 GitLab Runner 

GitLab Runner is an application that works with GitLab CI/CD to run jobs in a pipeline.

You can choose to install the GitLab Runner application on infrastructure that you own or manage. If you do, you should install GitLab Runner on a machine that’s separate from the one that hosts the GitLab instance for security and performance reasons. When you use separate machines, you can have different operating systems and tools, like Kubernetes or Docker, on each.

GitLab Runner is open-source and written in Go. It can be run as a single binary; no language-specific requirements are needed.

You can install GitLab Runner on several different supported operating systems. Other operating systems may also work, as long as you can compile a Go binary on them.

GitLab Runner can also run inside a Docker container or be deployed into a Kubernetes cluster.

GitLab Runner versions

For compatibility reasons, the GitLab Runner major. minor version should stay in sync with the GitLab major and minor version. Older runners may still work with newer GitLab versions, and vice versa. However, features may be not available or work properly if a version difference exists.

Backward compatibility is guaranteed between minor version updates. However, sometimes minor version updates of GitLab can introduce new features that require GitLab Runner to be on the same minor version.

If you host your own runners but host your repositories on GitLab.com, keep GitLab Runner updated to the latest version, as GitLab.com is updated continuously.

Runner registration

After you install the application, you register individual runners. Runners are the agents that run the CI/CD jobs that come from GitLab.

When you register a runner, you are setting up communication between your GitLab instance and the machine where GitLab Runner is installed.

Runners usually process jobs on the same machine where you installed GitLab Runner. However, you can also have a runner process jobs in a container, in a Kubernetes cluster, or in auto-scaled instances in the cloud.

Executors

When you register a runner, you must choose an executor.

An executor determines the environment each job runs in.

For example:

·         If you want your CI/CD job to run PowerShell commands, you might install GitLab Runner on a Windows server and then register a runner that uses the shell executor.

·         If you want your CI/CD job to run commands in a custom Docker container, you might install GitLab Runner on a Linux server and register a runner that uses the Docker executor.

These are only a few of the possible configurations. You can install GitLab Runner on a virtual machine and have it use another virtual machine as an executor.

When you install GitLab Runner in a Docker container and choose the Docker executor to run your jobs, it’s sometimes referred to as a “Docker-in-Docker” configuration.

Who has access to runners in the GitLab UI

Before you register a runner, you should determine if everyone in GitLab should have access to it, or if you want to limit it to a specific GitLab group or project.

There are three types of runners, based on who you want to have access:

·         Shared runners are for use by all projects

·         Group runners are for all projects and subgroups in a group

·         Specific runners are for individual projects

When you register a runner, you specify a token for the GitLab instance, group, or project. This is how the runner knows which projects it’s available for.

Tags

When you register a runner, you can add tags to it.

When a CI/CD job runs, it knows which runner to use by looking at the assigned tags.

For example, if a runner has the ruby tag, you would add this code to your project’s .gitlab-ci.yml file:

job:

  tags:

    - ruby

When the job runs, it uses the runner with the ruby tag.

Configuring runners

You can configure the runner by editing the config.toml file. This is a file that is installed during the runner installation process.

In this file you can edit settings for a specific runner, or for all runners.

You can specify settings like logging and cache. You can set concurrency, memory, CPU limits, and more.

Monitoring runners

You can use Prometheus to monitor your runners. You can view things like the number of currently-running jobs and how much CPU your runners are using.

Use a runner to run your job

After a runner is configured and available for your project, your CI/CD jobs can use the runner.

Specify the name of the runner or its tags in your .gitlab-ci.yml file. Then, when you commit to your repository, the pipeline runs, and the runner’s executor processes the commands.

Runners on GitLab.com

If you use GitLab.com, you can run your CI jobs on Runner Cloud. These are runners managed by GitLab and fully integrated with GitLab.com. These runners are enabled for all projects, though you can disable them.

If you don’t want to use runners managed by GitLab, you can install GitLab Runner and register your own runners on GitLab.com.

Features

GitLab Runner has the following features.

·         Run multiple jobs concurrently.

·         Use multiple tokens with multiple servers (even per-project).

·         Limit the number of concurrent jobs per-token.

·         Jobs can be run:

o    Locally.

o    Using Docker containers.

o    Using Docker containers and executing job over SSH.

o    Using Docker containers with autoscaling on different clouds and virtualization hypervisors.

o    Connecting to a remote SSH server.

·         Is written in Go and distributed as single binary without any other requirements.

·         Supports Bash, PowerShell Core, and Windows PowerShell.

·         Works on GNU/Linux, macOS, and Windows (pretty much anywhere you can run Docker).

·         Allows customization of the job running environment.

·         Automatic configuration reload without restart.

·         Easy to use setup with support for Docker, Docker-SSH, Parallels, or SSH running environments.

·         Enables caching of Docker containers.

·         Easy installation as a service for GNU/Linux, macOS, and Windows.

·         Embedded Prometheus metrics HTTP server.

·         Referee workers to monitor and pass Prometheus metrics and other job-specific data to GitLab.

Set up macOS runners

To run a CI/CD job on a macOS runner, complete the following steps in order.

When you’re done, GitLab Runner will be running on your macOS machine and an individual runner will be ready to process jobs.

·         Change the system shell to Bash.

·         Install Homebrew, rbenv, and GitLab Runner.

·         Configure rbenv and install Ruby.

·         Install Xcode.

·         Register a runner.

·         Configure CI/CD.

Prerequisites

Before you begin:

·         Install a recent version of macOS. This guide was developed on 11.4.

·         Ensure you have terminal or SSH access to the machine.

Change the system shell to Bash

Newer versions of macOS ship with Zsh as the default shell. You must change it to Bash.

1.      Connect to your machine and determine the default shell:

2.      echo $shell

3.      If the result is not /bin/bash, change the shell by running:

4.      chsh -s /bin/bash

5.      Enter your password.

6.      Restart your terminal or reconnect by using SSH.

7.      Run echo $SHELL again. The result should be /bin/bash.

Install Homebrew, rbenv, and GitLab Runner

The runner needs certain environment options to connect to the machine and run a job.

1.      Install the Homebrew package manager:

2.      /bin/bash -c "$(curl "https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh")"

3.      Set up rbenv, which is a Ruby version manager, and GitLab Runner:

4.      brew install rbenv gitlab-runner

5.      brew services start gitlab-runner

Configure rbenv and install Ruby

Now configure rbenv and install Ruby.

1.      Add rbenv to the Bash environment:

2.      echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.bash_profile

3.      source ~/.bash_profile

4.      Install Ruby 2.74 and set it as the machine’s global default:

5.      rbenv install 2.7.4

6.      rbenv global 2.7.4

Install Xcode

Now install and configure Xcode.

1.      Go to one of these locations and install Xcode:

o    The Apple App Store.

o    The Apple Developer Portal.

o    xcode-install. This project aims to make it easier to download various Apple dependencies from the command line.

2.      Agree to the license and install the recommended additional components. You can do this by opening Xcode and following the prompts, or by running the following command in the terminal:

3.      sudo xcodebuild -runFirstLaunch

4.      Update the active developer directory so that Xcode loads the proper command line tools during your build:

5.      sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Register a runner

Now register a runner to start picking up your CI/CD jobs.

1.      In GitLab, on the top bar, select Menu > Projects or Menu > Group to find your project or group.

2.      On the left sidebar, select Settings > CI/CD.

3.      Expand Runners.

4.      Note the URL and registration token.

5.      In a terminal, start the interactive setup:

6.      gitlab-runner register

7.      Enter the GitLab URL.

8.      Enter the registration token.

9.      Enter a description for the runner. You will use the description to identify the runner in GitLab, and the name is associated with jobs executed on this instance.

10.  Enter tags, which direct specific jobs to specific instances. You will use these tags later to ensure macOS jobs run on this macOS machine. In this example, enter:

11.  macos

12.  Type shell to select the shell executor.

A success message is displayed:

> Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

To view the runner, go to Settings > CI/CD and expand Runners.

Configure CI/CD

In your GitLab project, configure CI/CD and start a build. You can use this sample .gitlab-ci.yml file. Notice the tags match the tags you used to register the runner.

stages:

  - build

  - test

variables:

  LANG: "en_US.UTF-8"

 

before_script:

  - gem install bundler

  - bundle install

  - gem install cocoapods

  - pod install

build:

  stage: build

  script:

    - bundle exec fastlane build

  tags:

    - macos

test:

  stage: test

  script:

    - bundle exec fastlane test

  tags:

    - macos

The macOS runner should now build your project.