Runners
Runners are the agents that run the GitLab Runner application, to execute GitLab CI/CD jobs in a pipeline.
They are responsible for running your builds, tests, deployments, and other CI/CD tasks defined in .gitlab-ci.yml
files.
Runner execution flow
The following is a basic workflow of how runners work:
- A runner must first be registered with GitLab, which establishes a persistent connection between the runner and GitLab.
- When a pipeline is triggered, GitLab makes the jobs available to the registered runners.
- Matching runners pick up jobs, one job per runner, and execute them.
- Results are reported back to GitLab in real-time.
For more information, see Runner execution flow.
Runner job scheduling and execution
When a CI/CD job needs to be executed, GitLab creates a job based on the tasks defined in the .gitlab-ci.yml
file.
The jobs are placed in a queue. GitLab checks for available runners that match:
- Runner tags
- Runner types (like shared or group)
- Runner status and capacity
- Required capabilities
The assigned runner receives the job details. The runner prepares the environment and runs the job’s commands as specified in the .gitlab-ci.yml
file.
Runner categories
When deciding on which runners you want to execute your CI/CD jobs, you can choose:
- GitLab-hosted runners for GitLab.com or GitLab Dedicated users.
- Self-managed runners for all GitLab installations.
Runners can be group, project, or instance runners. GitLab-hosted runners are instance runners.
GitLab-hosted runners
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Dedicated
GitLab-hosted runners are:
- Fully managed by GitLab.
- Available immediately without setup.
- Run on fresh VMs for each job.
- Include Linux, Windows, and macOS options.
- Automatically scaled based on demand.
Choose GitLab-hosted runners when:
- You want zero-maintenance CI/CD.
- You need quick setup without infrastructure management.
- Your jobs require isolation between runs.
- You’re working with standard build environments.
- You’re using GitLab.com or GitLab Dedicated.
Self-managed runners
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Self-managed runners are:
- Installed and managed by you.
- Run on your own infrastructure.
- Customizable to your needs.
- Support various executors (including Shell, Docker, and Kubernetes).
- Can be shared or set to specific projects or groups.
Choose self-managed runners when:
- You need custom configurations.
- You want to run jobs in your private network.
- You require specific security controls.
- You require project or group runners.
- You need to optimize for speed with runner reuse.
- You want to manage your own infrastructure.
Related topics
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
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 GitLab subscription).
Request support