The execution of modern software delivery relies heavily on the seamless orchestration of Continuous Integration and Continuous Deployment (CI/CD) pipelines. At the center of this orchestration is the GitLab Runner, the specialized application responsible for acting as the engine for these pipelines. When a developer pushes code or opens a merge request, GitLab triggers a pipeline, and it is the Runner that receives these jobs, executes the specific tasks defined in the configuration, and transmits the results back to the GitLab server. This mechanism is fundamental to automating the complex processes of building, testing, and deploying software changes.
To maintain a high-performing DevOps ecosystem, an engineer must possess the ability to view, monitor, and manage these runners. Viewing runners is not merely a matter of looking at a list; it involves understanding the scope of runner availability, analyzing performance metrics through statistical medians, tracking connectivity status, and identifying security vulnerabilities through version auditing. Understanding how to view runners at the instance, group, and project levels is critical for ensuring that the infrastructure used to run pipelines is performant, flexible, and secure.
Categorization and Scope of Runner Visibility
GitLab runners are not monolithic entities; they are categorized based on their availability and their relationship to the GitLab hierarchy. The ability to view a runner is strictly tied to the user's role and the specific runner's scope.
The primary categories of runners include:
- Shared Runners: These are provided by GitLab and are available across all projects on GitLab.com. While they provide immediate utility for quick and simple jobs, their performance may be inconsistent because they operate on shared resources.
- Specific Runners: These are dedicated to a particular project or a specific group of projects. Because they are typically installed and maintained by the project team, they offer significantly more control over the execution environment and the underlying hardware resources.
The visibility of these runners within the GitLab interface is governed by the scope of the user's permissions and the organizational structure of the instance.
| Runner Type | Availability | Primary Use Case | Management Responsibility |
|---|---|---|---|
| Shared Runners | Global across GitLab.com | Quick, simple, non-specialized jobs | GitLab |
| Specific Runners | Project or Group specific | Specialized environments and high-control tasks | Project/Group Team |
Managing Runner Visibility in Groups
For users working within a group context, viewing runners requires specific administrative or ownership privileges. To access the runner view for a group:
- Navigate to the left sidebar in the GitLab interface.
- Use the Search function or navigate directly to the desired group.
- Select the Build menu.
- Select Runners.
By default, the interface is configured to show only the runners that are inherited from the instance or from parent groups. This "Show only inherited" behavior ensures that group-level users are not overwhelmed by instance-wide runners that may not be relevant to their specific group tasks. If an administrator or an Owner of the group needs to see the full spectrum of available runners, including those provided by the instance or residing in other groups, they must perform the following:
- Navigate to the group via the left sidebar.
- Select Build > Runners.
- Locate the "Show only inherited" toggle above the list.
- Turn the toggle off to reveal all available runners in the instance.
Note that possessing the Owner role for the group is a prerequisite for managing these visibility settings. Furthermore, an administrator has the capability to pause a runner, which effectively prevents it from accepting any new jobs from the subgroups or projects contained within the GitLab instance.
Statistical Analysis and Performance Monitoring
For large-scale deployments, simply knowing a runner exists is insufficient; administrators must understand how that runner performs under load. GitLab provides sophisticated telemetry to allow for the monitoring of the runner fleet.
Accessing Runner Metrics
To view the performance statistics of the runner fleet, an administrator must access the high-level management area:
- Select Admin from the bottom of the left sidebar.
- Navigate to CI/CD > Runners.
- Select the View metrics option.
This feature is particularly vital for users on the Ultimate tier, offering enhanced visibility for GitLab.com, GitLab Self-Managed, and GitLab Dedicated environments.
Understanding Median Job Queued Time
One of the most critical metrics provided is the median job queued time. This value is essential for identifying bottlenecks in the CI/CD pipeline. The median represents the 50th percentile of the queue duration. In practical terms, this means that exactly half of the jobs queue for a duration longer than the median value, and the other half queue for less time than the median value.
The calculation of this metric is performed using a sampling method:
- The system considers the most recent 100 jobs run by Instance runners.
- The calculation is based on a subset of the latest 5000 runners.
This statistical approach allows administrators to gauge the responsiveness of their infrastructure and determine if more specific runners need to be provisioned to handle increased load.
Lifecycle Management and Version Auditing
A runner's lifecycle involves registration, active execution, and periodic maintenance. Failure to monitor the status and version of a runner can lead to pipeline failures or security vulnerabilities.
Monitoring Runner Status and Connectivity
When viewing the list of runners, the status of each runner is explicitly stated. A critical status to monitor is never_contacted.
- never_contacted: This indicates that the runner has never successfully established a connection with the GitLab instance. This typically occurs after a new registration that hasn't been activated. To resolve this and force the runner to contact GitLab, the command
gitlab-runner runmust be executed on the host machine.
GitLab manages its database by periodically deleting stale runner managers. If a runner successfully contacts the GitLab instance, the connection is recreated, ensuring the database remains lean and relevant.
The Necessity of Version Upgrades
Maintaining an up-to-date GitLab Runner is a non-negotiable requirement for secure and stable operations. The version of the runner used must be kept current to ensure compatibility with the GitLab instance and to protect the infrastructure.
When viewing the list of runners—either at the group level (via Build > Runners) or at the instance level (via Admin > CI/CD > Runners)—the status will indicate if a runner is outdated.
| Status Label | Description and Impact |
|---|---|
| Outdated - recommended | The runner is not on the latest PATCH version. This creates a risk of security vulnerabilities or high-severity bugs. |
| Outdated - major | The runner is one or more MAJOR versions behind the GitLab instance. This may result in specific features being unavailable or failing to function correctly. |
IP Address Identification
For network troubleshooting and security auditing, knowing the IP address of a runner is essential. GitLab retrieves this information by inspecting the source of the HTTP requests sent when the runner polls the server for new jobs. This IP address is automatically updated in the GitLab interface whenever the runner updates its connection.
The method for viewing the IP address depends on the user's role and the runner's scope:
- For Instance Runners: An administrator must go to Admin > CI/CD > Runners and locate the IP Address column in the runner table.
- For Project Runners: A user with the Owner role for the project must go to Settings > CI/CD, expand the Runners section, select the specific runner name, and locate the IP Address row.
This capability was introduced in GitLab 16.11 to provide better visibility into the network footprint of the runner fleet.
Runner Registration and Command-Line Management
While the web interface provides visibility, the gitlab-runner command-line tool provides the actual control mechanism for the runner's existence. The registration process is the foundational step that links a piece of infrastructure to the GitLab ecosystem.
The Registration Workflow
To register a new runner, the gitlab-runner register command is used. This process requires superuser privileges on the host machine to interact with system-level configurations.
The syntax for registration is as follows:
bash
sudo gitlab-runner register --url https://gitlab.example.com --registration-token token --name name
During this interactive process, the user is prompted for several key pieces of information:
- GitLab instance URL: The endpoint where the runner will connect (e.g.,
https://about.gitlab.com/or a self-hosted URL). - Registration token: The unique identifier obtained from the GitLab project or group.
- Description: A user-defined string to identify the runner (e.g., "Project Build Runner").
- Tags: Optional labels used to assign specific jobs to this runner.
- Executor: The environment in which the jobs will run (e.g., Docker, Shell, etc.).
Security Evolution: The Deprecation of Registration Tokens
It is vital for administrators to be aware of a major shift in GitLab security architecture. In GitLab 17.0, the use of runner registration tokens is disabled across all GitLab instances. To manage runners in this new security landscape, administrators must ensure that registration tokens are enabled in the Admin area if they wish to allow members of projects and groups to create runners using these tokens.
To enable this capability:
- Navigate to the group via the left sidebar.
- Select Settings > CI/CD.
- Expand the Runners section.
- Toggle the "Allow members of projects and groups to create runners with runner registration tokens" option.
Technical Analysis of Runner Operations
The relationship between the GitLab server and the runner is a polling-based architecture. The runner acts as a client that periodically reaches out to the GitLab instance to ask, "Do you have any jobs for me?" This design allows runners to reside behind firewalls or in private networks, as they do not require the GitLab server to initiate an inbound connection to the runner.
The efficiency of this relationship is measured by the latency between a job being created and the runner picking it up. The previously discussed median job queued time is the primary KPI for this latency. If the median time increases, it indicates that the current fleet of runners is insufficient for the volume of incoming CI/CD requests, necessitating the registration of additional specific runners to distribute the load.
The management of runners is a multi-layered responsibility. From a high-level administrative view, one must monitor versioning to prevent security breaches and analyze medians to ensure pipeline velocity. From a project-level view, one must manage the specific runners and their tags to ensure that jobs are executed in the correct environments. As GitLab continues to evolve its security model by moving away from traditional registration tokens, the ability to view and manage these agents through the administrative and group-level interfaces becomes increasingly critical to the continuity of the software development lifecycle.