Install GitLab Runner

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed

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 Kubernetes 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 your GitLab instance. The GitLab instance can be self-managed or you can use GitLab.com. You can also follow the tutorial, Create, register, and run your own project runner.

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.

GitLab Runner officially supported binaries are available for the following architectures:

  • x86, AMD64, ARM64, ARM, s390x, ppc64le

Official packages are available for the following Linux distributions:

  • CentOS, Debian, Ubuntu, RHEL, Fedora, Mint, Oracle, Amazon

GitLab Runner officially supports the following operating systems. If you prefer to use a different operating system that is not officially supported, it must be able to compile a Go binary.

  • Linux, Windows, macOS, FreeBSD
note
For security and performance reasons, you should install GitLab Runner on a machine that is separate to the machine that hosts your GitLab instance.

System Requirements

GitLab Runner system requirements vary widely and depend on variables unique to each use-case. GitLab Runner instances can be sized individually given these variables and scaled higher or lower as necessary. These variables include:

  • The anticipated:
    • CPU load of CI jobs.
    • Memory usage of CI jobs.
  • The number of:
    • Concurrent CI jobs.
    • Projects in active development.
    • Developers expected to work in parallel.

For more information, see what machine types are available for Linux (x86-64) on SaaS.

FIPS compliant GitLab Runner

In GitLab Runner 14.7 and later, a GitLab Runner binary that is FIPS 140-12 compliant is provided. This binary, built with the Red Hat Go compiler, bypasses the standard library cryptographic routines and instead calls into a FIPS 140-2 validated cryptographic library.

In GitLab Runner 15.1 and later, a UBI-8 minimal is used as the base for creating the GitLab Runner FIPS image.

note
Only Red Hat Enterprise Linux (RHEL) distributions are supported.

FIPS compliant GitLab Runner binaries are provided for the following architectures:

  • AMD64

Docker images and RPM packages for the same architectures are also provided.

FIPS compliant GitLab Runner in RHEL

When you use the FIPS version of GitLab Runner in RHEL, you should enable FIPS mode.

FIPS compliant GitLab Runner in other systems and architectures

Refer to this issue to follow progress on adding other architectures and distributions.

Repositories

Binaries

Containers

Autoscale

Upgrading GitLab Runner

To upgrade your version of GitLab Runner, see the instructions for each operating system: