CI/CD runners

0 Preface/Foreword

This tutorial shows you how to configure and run your first runner in GitLab.

A runner is an agent in the GitLab Runner application that runs jobs in a GitLab CI/CD pipeline. Jobs are defined in configuration file and assigned to available runners.

GitLab has three types of runners:

• Shared: Available to all groups and projects in a GitLab instance.
• Group: Available to all projects and subgroups in a group
• Project: Associated with specific projects. Typically, project runners are used by one project at a time.

0.1 参考文献

Tutorial: Create, register, and run your own project runner | GitLab

Install GitLab Runner | GitLab

1 Runners

For this tutorial, you'll create a project runner to run jobs defined in a basic pipeline configuration:

1. Create a blank project.
2. Create a project pipeline.
3. Create and register a project runner.
4.  Trigger a pipeline to run your runner.

 1.1 Create a blank project

First, create a blank project where you can create your CI/CD pipeline and runner.

To create a blank project:

1. On the left sidebar, at the top, select Create new (+) and new project/repository.
2. Select create blank project.
3. Enter project details: 1) in the project name field, enter the name of your project. The name must start with a lowercase or uppercase letter (a-zA-Z), digit (0-9), emoji, or underscore (_). It can also contain dots (.), pluses (+), dashes (-), or space. 2)I n the project slug field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug.
4. Select Create project.

1.2 Create a project pipeline

Next, create a configuration file for your project. This a YAML file where you specify instructions for GtiLab CI/CD.

In this file, you define :

• The structure and order of jobs that the runner should execute.
• The decisions the runner should make when specific conditions are encountered.

1. on the left sidebar, select search or go to find your project or group.
2. select the plus icon (+), then select new file.
3. in the filename field, enter .gitlab-ci.yml
4. in the large text box, paste this sample configuration:

stages:

 - build

 - test

job_build:

  stage: build

  script:

     - echo "Building the project"

job_test:

  stage: test

  script:

      - echo "Running tests"

1.3 Create and register a project runner

 Next, create a project runner and register it. You must register the runner to link it ot GitLab so that it can pick up jobs from the project pipeline.

To create a project runner:

1. on the left sidebar, select search or go to and find your project,
2. select settings > CI/CD
3. expand the runners section
4. select new project runner
5. select your operating system
6. in the tags section, select the Run untagged checkbox. Tags specify which jobs the runner can run an are optional.
7. select create runner
8. Follow the on-screen instructions to register the runner from the command line. When prompted: 1) For executor, because your runner will run directly on the host computer, enter shell. The executor is the environment where the runner executes the job. 2) For GitLab instance URL, use the URL for your GitLab instance. For example, if your project is hosted on gitlab.example.com/yourname/yourproject, then your GitLab instance URL is https://gitlab.example.com. If your project is hosted on GitLab.com, the URL is https://gitlab.com.
9. start your runner: gitlab-runner run

1.4 check the runner configuration file

After you register the runner, the configuration and runner authentication token is saved to your config.toml. The runner uses the token to authenticate with GitLab when picking up jobs from the job queue. 

You can use the config.toml to define more advanced runner configurations.

Here's what your config.toml should look like after you register and start the runner:

[[runners]]

name = "my-project-runner1"

url = "http://127.0.0.1:3000"

id = 38 token = "glrt-TOKEN"

token_obtained_at = 2023-07-05T08:56:33Z

token_expires_at = 0001-01-01T00:00:00Z

executor = "shell"

1.5 Trigger a pipeline to run your runner

Next, trigger a pipeline in your project so that you can view your runner exexute a job.

1. on the left sidebar, select search or go to and find your project.
2. seclect Build > pipelines
3. select Run pipeline.
4. select a job to view the job log. The output should look similar to this example, which shows your runner successfully executing the job:

Running with gitlab-runner 16.2.0 (782e15da)

on my-project-runner TOKEN, system ID: SYSTEM ID

Preparing the "shell" executor

00:00

Using Shell (bash) executor...

Preparing environment

00:00

/Users/username/.bash_profile: line 9: setopt: command not found

Running on MACHINE-NAME...

Getting source from Git repository

00:01

/Users/username/.bash_profile: line 9: setopt: command not found

Fetching changes with git depth set to 20...

Reinitialized existing Git repository in /Users/username/project-repository

Checking out 7226fc70 as detached HEAD (ref is main)...

Skipping object checkout, Git LFS is not installed for this repository.

Consider installing it with 'git lfs install'.

Skipping Git submodules setup

Executing "step_script" stage of the job script

00:00

/Users/username/.bash_profile: line 9: setopt: command not found $ echo "

Building the project"

Building the project

Job succeeded

2 Install GitLab runner

GitLab Runner runs the CI/CD jobs that are defined in GitLab.

You can install GitLab Runner on your infrastructure, inside a Docker container, or deployed to a Kubuernetes cluster.

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

After you install GitLab Runner, you must create and register runners with you GitLab instance. The GitLab instance can be self-managed or you can use GitLab.com.

GitLab Runner can be installed and used on GNU/Linux, macOS, FreeBSD, and Windows. You can install it:

• In a container.
• By downloading a binary manually.
• By using a repository for rpm/deb packages

For security and performance reasons, you should install GitLab Runner on a machine that is separate to the machine that hosts your GitLab instance.