- Compatibility with GitLab versions
- Install GitLab Runner
- Register GitLab Runner
- Using GitLab Runner
- Selecting the executor
- Configuring GitLab Runner
- Release process
GitLab Runner is the lightweight, highly-scalable agent that runs your build jobs and sends the results back to a GitLab instance.
GitLab Runner works in conjunction with GitLab CI/CD, the open-source continuous integration service included with GitLab.
This documentation includes details about installing and setting up GitLab Runner, and registering and configuring individual runners.
If you already have runners set up and you need help using them in your GitLab instance, the information you need may be in the main GitLab documentation.
For example, visit the main GitLab documentation to learn more about:
- How to configure a runner in GitLab.
- How to run a CI/CD job in a Docker container.
- How GitLab CI/CD works.
GitLab Runner is an open-source project written in Go and can be run as a single binary. No language specific requirements are needed.
It is designed to run on the GNU/Linux, macOS, and Windows operating systems. Other operating systems might work as long as you can compile a Go binary on them.
If you want to use Docker, install the latest version.
GitLab Runner requires a minimum of Docker
- Running multiple jobs concurrently.
- Using multiple tokens with multiple servers (even per-project).
- Limiting number of concurrent jobs per-token.
- Jobs can be run:
- Using Docker containers.
- Using Docker containers and executing job over SSH.
- Using Docker containers with autoscaling on different clouds and virtualization hypervisors.
- Connecting to a remote SSH server.
- Is written in Go and distributed as single binary without any other requirements.
- Supports Bash 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.
The GitLab Runner version should be in sync with the GitLab version. Older runners may still work with newer GitLab versions (and vice versa). However, features may be not available or work properly if there’s a version difference.
Backward compatibility is guaranteed between minor version updates. However, be aware that minor version updates of GitLab can introduce new features that require the Runner to be on the same minor version.
GitLab Runner can be installed and used on GNU/Linux, macOS, FreeBSD, and Windows. You can install it using Docker, download the binary manually or use the repository for rpm/deb packages that GitLab offers. Below you can find information on the different installation methods:
- Install using GitLab’s repository for Debian/Ubuntu/CentOS/RedHat (preferred).
- Install on GNU/Linux manually (advanced).
- Install on macOS.
- Install on Windows.
- Install as a Docker service.
- Install in autoscaling mode using Docker machine.
- Install on FreeBSD.
- Install on Kubernetes.
- Install the nightly binary manually (development).
Once GitLab Runner is installed, you need to register it with GitLab.
Learn how to register a GitLab Runner.
GitLab Runner implements a number of executors that can be used to run your builds in different scenarios. If you are not sure what to select, read the I am not sure section. Visit the compatibility chart to find out what features each executor supports and what not.
To jump into the specific documentation of each executor, see:
- Docker Machine and Docker Machine SSH (autoscaling).
No development of new executors is planned and we are not accepting contributions for new ones. Please check CONTRIBUTION.md for details.
See information on configuring GitLab Runner, and:
- Advanced configuration options: Learn how to use the TOML configuration file that GitLab Runner uses.
- Use self-signed certificates: Configure certificates that are used to verify TLS peer when connecting to the GitLab server.
- Autoscaling using Docker machine: Execute jobs on machines that are created on demand using Docker machine.
- Autoscaling GitLab Runner on AWS
- The init system of GitLab Runner: Learn how the Runner installs its init service files based on your operating system.
- Supported shells: Learn what shell script generators are supported that allow to execute builds on different systems.
- Security considerations: Be aware of potential security implications when running your jobs with GitLab Runner.
- Runner monitoring: Learn how to monitor the Runner’s behavior.
- Cleanup the Docker images automatically: A simple Docker application that automatically garbage collects the GitLab Runner caches and images when running low on disk space.
- Configure GitLab Runner to run behind a proxy: Learn how to set up a Linux proxy and configure GitLab Runner. Especially useful for the Docker executor.
- Feature Flags: Learn how to use feature flags to get access to features in beta stage or to enable breaking changes before the full deprecation and replacement is handled.
- Configure Session Server: Learn how to configure a session server for interacting with jobs the Runner is responsible for.
Read the FAQ for troubleshooting common issues.
The description of release process of the GitLab Runner project can be found in PROCESS.md
Contributions are welcome, see
CONTRIBUTING.md for more details.
See the development documentation to hack on GitLab Runner.
If you’re a reviewer of GitLab Runner project, then please take a moment to read the Reviewing GitLab Runner document.
See the CHANGELOG to view recent changes.
This code is distributed under the MIT license, see the LICENSE file.