You can choose to install the GitLab Runner application on infrastructure that you own or manage. If you do, you should install GitLab Runner on a machine that’s separate from the one that hosts the GitLab instance for security and performance reasons. When you use separate machines, you can have different operating systems and tools, like Kubernetes or Docker, on each. Show GitLab Runner is open-source and written in Go. It can be run as 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 Go binary on them. GitLab Runner can also run inside a Docker container or be deployed into a Kubernetes cluster. Scaling a fleet of runnersWhen 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 versionsFor 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. note 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 is updated continuously. Runner registrationAfter you install the application, you register individual 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. ExecutorsWhen 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 the Docker executor to run your jobs, it’s sometimes referred to as a “Docker-in-Docker” configuration. Who has access to runners in the GitLab UIBefore 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:
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. TagsWhen you register a runner, you can add 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
When the job runs, it uses the runner with the Configuring runnersYou can configure the runner by editing the 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 runnersYou 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 your jobAfter a runner is configured and available for your project, your CI/CD jobs can use the runner. Specify the name of the runner or its tags in your Runners on GitLab.comIf you use GitLab.com, you can run your CI/CD jobs on runners hosted by GitLab. These runners are managed by GitLab and fully integrated with GitLab.com. These runners are enabled for all projects, though . If you don’t want to use runners managed by GitLab, you can install GitLab Runner and register your own runners on GitLab.com. FeaturesGitLab Runner has the following features.
Runner execution flowThis diagram shows how runners are registered and how jobs are requested and handled. It also shows which actions use , 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 TroubleshootingLearn how to troubleshoot common issues. ContributingContributions are welcome. See If you’re a reviewer of GitLab Runner project, take a moment to read the Reviewing GitLab Runner document. |