GitLab Runner Docs

GitLab Runner is the open source project that is used to run your jobs and send the results back to GitLab. It is used in conjunction with GitLab CI/CD, the open-source continuous integration service included with GitLab that coordinates the jobs.

Requirements

GitLab Runner is 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 will probably 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 v1.13.0.

Features

  • Allows:
    • Running multiple jobs concurrently.
    • Using multiple tokens with multiple servers (even per-project).
    • Limiting number of concurrent jobs per-token.
  • Jobs can be run:
    • Locally.
    • Using Docker containers.
    • Using Docker containers and executing job over SSH.
    • Using Docker containers with autoscaling on different clouds and virtualization hypervisors.
    • Connecting to 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.

Compatibility with GitLab versions

The GitLab Runner version should be in sync with the GitLab version. While older Runners may still work with newer GitLab versions, and vice versa, in some cases, features may be not available or work properly if there’s a version difference.

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

Install GitLab Runner

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:

Register GitLab Runner

Once GitLab Runner is installed, you need to register it with GitLab.

Learn how to register a GitLab Runner.

Using GitLab Runner

Selecting the executor

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:

No development of new executors is planned and we are not accepting contributions for new ones. Please check CONTRIBUTION.md for details.

Configuring GitLab Runner

See information on configuring GitLab Runner, and:

Troubleshooting

Read the FAQ for troubleshooting common issues.

Release process

The description of release process of the GitLab Runner project can be found in PROCESS.md

Contributing

Contributions are welcome, see CONTRIBUTING.md for more details.

Development

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.

Changelog

See the CHANGELOG to view recent changes.

License

This code is distributed under the MIT license, see the LICENSE file.