GitLab Runner | GitLab Docs (original) (raw)

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

Use self-managed runners

Self-managed runners are GitLab Runner instances that you install, configure, and manage in your own infrastructure. You can install and register self-managed runners on all GitLab installations.

Unlike GitLab-hosted runners, which are hosted and managed by GitLab, you have complete control over self-managed runners.

Use Terraform to create and manage a fleet of runners

Many common runner configurations can be created and managed by using theGitLab Runner Infrastructure Toolkit (GRIT). GRIT is a library of Terraform modules used to create and manage many common runner configurations on public cloud providers. GRIT is created and maintained by the runner team.

Scale a fleet of runners

When your organization scales to having a fleet of runners, you should plan for how you will monitor and adjust performance for these runners.

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 not be 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.

GitLab Runner 15.0 introduced a change to the registration API request format. It prevents the GitLab Runner from communicating with GitLab versions lower than 14.8. You must use a Runner version that is appropriate for the GitLab version, or upgrade the GitLab application.

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

Runner registration

After you install the application, you registerindividual 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:

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 theDocker executorto 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:

The scope of a runner is defined during the registration. 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. Tags are the only way to filter the list of available runners for a job.

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

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

Configuring runners

You can configurethe 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 jobs

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

Features

GitLab Runner has the following features.

Runner execution flow

This diagram shows how runners are registered and how jobs are requested and handled. It also shows which actions use registration, authentication, and job tokens.

sequenceDiagram participant GitLab participant GitLabRunner participant Executor

opt registration
  GitLabRunner ->>+ GitLab: POST /api/v4/runners with registration_token
  GitLab -->>- GitLabRunner: Registered with runner_token
end

loop job requesting and handling
  GitLabRunner ->>+ GitLab: POST /api/v4/jobs/request with runner_token
  GitLab -->>+ GitLabRunner: job payload with job_token
  GitLabRunner ->>+ Executor: Job payload
  Executor ->>+ GitLab: clone sources with job_token
  Executor ->>+ GitLab: download artifacts with job_token
  Executor -->>- GitLabRunner: return job output and status
  GitLabRunner -->>- GitLab: updating job output and status with job_token
end

Glossary

This glossary provides definitions for terms related to GitLab Runner.

See also the official GitLab Word List and the GitLab Architecture entry for GitLab Runner.

Troubleshooting

Learn how to troubleshoot common issues.

Contributing

Contributions are welcome. See CONTRIBUTING.mdand the development documentation for details.

If you’re a reviewer of GitLab Runner project, take a moment to read theReviewing GitLab Runner document.

You can also review the release process for the GitLab Runner project.

Changelog

See the CHANGELOG to view recent changes.

License

This code is distributed under the MIT license. View the LICENSE file.