- Runner registration
GitLab Runner is an application that works with GitLab CI/CD to run jobs in a pipeline.
Amazon Linux is available on Amazon EC2 instances. For full install instructions, see Docker basics for Amazon ECS. After launching the official Amazon Linux EC2 image, update the installed packages and install the most recent Docker CE packages: $. 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.
You can choose to install the GitLab Runner applicationon infrastructure that you own or manage. If you do, you should installGitLab Runner on a machine that’s separate from the one that hosts the GitLab instancefor security and performance reasons. When you use separate machines, you can havedifferent operating systems and tools, like Kubernetes or Docker, on each.
GitLab Runner is open-source and written in Go. It can be runas a single binary; no language-specific requirements are needed.
You can install GitLab Runner on several different supported operating systems.Other operating systems may also work, as long as you can compile a Gobinary on them.
GitLab Runner can also run inside a Docker container or be deployed into a Kubernetes cluster.
View some best practices for how to use and administer GitLab Runner.
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 workwith newer GitLab versions, and vice versa. However, features may be not available or work properlyif a version difference exists.
Backward compatibility is guaranteed between minor version updates. However, sometimes minorversion updates of GitLab can introduce new features that require GitLab Runner to be on the same minorversion.
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 yourGitLab 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:
- If you want your CI/CD job to run PowerShell commands, you might install GitLabRunner on a Windows server and then register a runner that uses the shell executor.
- If you want your CI/CD job to run commands in a custom Docker container,you might install GitLab Runner on a Linux server and register a runner that usesthe Docker executor.
These are only a few of the possible configurations. You can install GitLab Runneron 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 GitLabshould 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:
- Shared runners are for use by all projects
- Group runners are for all projects and subgroups in a group
- Specific runners are for individual projects
When you register a runner, you specify a token for the GitLab instance, group, or project.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.
For example, if a runner has the ruby
tag, you would add this code toyour 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 howmuch CPU your runners are using.
Use a runner to run your job
After a runner is configured and available for your project, yourCI/CD jobs can use the runner.
Specify the name of the runner or its tags in your.gitlab-ci.yml
file.Then, when you commit to your repository, the pipeline runs, andthe runner’s executor processes the commands.
Runners on GitLab.com
If you use GitLab.com, GitLab manages runners for you.These runners are enabled for all projects, thoughyou can disable them.
If you don’t want to use runners managed by GitLab, you can install GitLab Runner andregister your own runners on GitLab.com.
Features
GitLab Runner has the following features.
- Run multiple jobs concurrently.
- Use multiple tokens with multiple servers (even per-project).
- Limit the 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 a remote SSH server.
- Is written in Go and distributed as single binary without any other requirements.
- Supports Bash, PowerShell Core, 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.
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.
Troubleshooting
Learn how to troubleshoot common issues.
Contributing
Contributions are welcome. See CONTRIBUTING.md
and 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
Install Prometheus Grafana Docker
See the CHANGELOG to view recent changes.
License
This code is distributed under the MIT license. View the LICENSE file.
Help & feedback
Docs
Edit this pageto fix an error or add an improvement in a merge request.Create an issueto suggest an improvement to this page.
Product
Create an issueif there's something you don't like about this feature.Propose functionalityby submitting a feature request.
Join First Lookto help shape new features.
Feature availability and product trials
View pricingto see all GitLab tiers and features, or to upgrade.Try GitLab for freewith access to all features for 30 days.
Get Help
Install Prometheus Node Exporter Docker
If you didn't find what you were looking for,search the docs.
If you want help with something specific and could use community support,post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLabsubscription).