Architectural Implementation and Deployment of GitLab Runner on CentOS 7 Environments

The deployment of GitLab Runner within a CentOS 7 ecosystem represents a critical junction in the Continuous Integration and Continuous Deployment (CI/CD) pipeline. As an orchestration component, the GitLab Runner is responsible for executing the jobs defined in the .gitlab-ci.yml configuration file, thereby bridging the gap between source code commits and automated testing or deployment. In a CentOS 7 environment, which is characterized by its stability and enterprise-grade reliability, the installation process requires precise handling of package managers, user permissions, and security configurations, particularly when TLS (Transport Layer Security) is integrated for secure communications.

The runner operates as a lightweight agent that communicates with the GitLab server. While the legacy GitLab CI Multi Runner project has been deprecated in favor of the modern Go-based GitLab Runner, the functional requirement remains the same: providing a scalable execution environment for automated tasks. For users operating within CentOS 7, RHEL, or Fedora, the installation can be achieved through official repository integration, specific RPM package management, or direct binary execution. This article provides a granular breakdown of these methodologies, ranging from standard repository installations to complex TLS-secured configurations for Docker-based executors.

Repository Integration and Package Management

The most efficient way to maintain a GitLab Runner on a CentOS 7 system is to integrate the official GitLab repositories. This ensures that the system can pull updates, security patches, and specific version increments through the standard yum package manager.

To initiate the repository setup, a shell script provided by GitLab must be executed with administrative privileges. This script configures the necessary Yum repository files to allow the system to recognize the GitLab package ecosystem.

bash curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh" | sudo bash

Once the repository is added, the user has several paths for installation depending on whether they require the bleeding-edge version or a specific, stable iteration required for legacy compatibility.

Standard and Version-Specific Installations

For most standard deployments, the latest version available in the repository is preferred. This is achieved through the following command:

bash sudo yum install gitlab-runner

In enterprise environments where testing cycles require specific versions (such as version 10.0.0), the user must first query the available versions within the repository to identify the exact string required for the installation.

bash yum list gitlab-runner --showduplicates | sort -r

After identifying the target version, the installation can be targeted specifically:

bash sudo yum install gitlab-runner-10.0.0-1

Binary-Based Deployment for Manual Control

When repository management is not desired or when the environment requires a specific architecture not easily serviced by the RPM repository, manual binary deployment is a viable alternative. This method involves downloading the specific binary for the host's CPU architecture and placing it in a directory within the system's PATH, typically /usr/local/bin/.

The following table provides the specific download commands for various architectures:

Service Management and User Permissions

After the installation of the GitLab Runner package, the system creates a dedicated system user named gitlab-runner. This user facilitates the execution of the runner service under a non-privileged account, adhering to the principle of least privilege.

Verifying Service Status and Control

The runner operates as a background service. Users must be able to verify its operational state and manipulate its lifecycle (start, stop, restart) to ensure continuous availability for CI/CD jobs.

To check the current version of the installed runner:

bash sudo gitlab-runner -version

To check if the service is currently active and running:

bash sudo gitlab-runner status

The following commands are used to manage the service state:

• sudo gitlab-runner start
• sudo gitlab-runner stop
• sudo gitlab-runner restart

Granting Sudo Privileges to the Runner User

In many CI/CD workflows, the runner needs to execute commands that require elevated privileges, such as managing Docker containers or modifying system configurations. To allow the gitlab-runner user to execute these commands without manual intervention, it must be granted sudo permissions via the visudo utility.

1. Open the sudoers file:
   bash sudo visudo

2. Append the following lines to the file to allow the user to execute commands with NOPASSWD:
   text gitlab-runner ALL=(ALL:ALL) ALL gitlab-runner ALL=(ALL) NOPASSWD: ALL

This configuration ensures that the runner can perform administrative tasks necessary for containerized builds without the overhead of a password prompt, which would otherwise hang the automated job.

Advanced Configuration: TLS-Enabled Deployment on CentOS 7

For high-security environments, deploying a GitLab Runner version 14.0.0 with TLS enabled is a specialized procedure. This is particularly relevant when the runner interacts with Docker via encrypted channels. This process involves preparing the local environment, setting up OpenSSL configurations, and handling the directory structures required for secure communication.

Environment Preparation and Package Installation

The deployment starts with the manual acquisition of the specific RPM package and the verification of its digital signature to ensure integrity.

bash wget 'https://packages.gitlab.com/runner/gitlab-runner/packages/el/7/gitlab-runner-14.0.0-1.x86_64.rpm/download.rpm' mv download.rpm gitlab-runner-14.0.0-1.x86_64.rpm rpm --checksig gitlab-runner-14.0.0-1.x86_64.rpm yum install -y gitlab-runner-14.0.0-1.x86_64.rpm

Docker Group Integration and Directory Setup

Since the runner will likely utilize the Docker executor, the gitlab-runner user must be a member of the docker group to interact with the Docker daemon. Furthermore, necessary directories for Docker and OpenSSL must be established.

bash usermod -aG docker gitlab-runner mkdir -p ~/.docker mkdir -p /etc/docker

OpenSSL Configuration for Client and Server

To facilitate TLS, custom OpenSSL configuration files must be generated. This involves defining request extensions, distinguished names, and key usage parameters.

The client-side configuration is applied to the gitlab-runner user's home directory:

bash touch ~/.docker/openssl.cnf cat <<EOF > /root/.docker/openssl.cnf [req] req_extensions = v3_req distinguished_name = req_distinguished_name [req_distinguished_name] [ v3_req ] basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment extendedKeyUsage = serverAuth, clientAuth EOF

The server-side configuration requires additional parameters, specifically the Subject Alternative Name (SAN), to ensure the certificate is valid for the specific IP addresses of the host. The script dynamically captures the host's IP address to populate these fields.

bash IP_address=$(hostname -I | head -c 11) touch /etc/docker/openssl.cnf cat <<EOF > /etc/docker/openssl.cnf [req] req_extensions = v3_req distinguished_name = req_distinguished_name [req_distinguished_name] [ v3_req ] basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment extendedKeyUsage = serverAuth, clientAuth subjectAltName = @alt_names [alt_names] IP.1=127.0.0.1 IP.2=$IP_address EOF

Registration and Lifecycle Management

Once the software is installed and configured, the runner must be registered with the GitLab instance to begin receiving jobs.

The Registration Process

Registration connects the runner to a specific GitLab project or instance using a URL and a unique registration token. This can be done through an interactive session or via a non-interactive command for automated setups.

For a standard registration, use:

bash sudo gitlab-runner register

For a non-interactive registration utilizing a Docker executor, the command is more comprehensive:

bash sudo gitlab-runner register \ --non-interactive \ --url "GITLAB_SERVER_URL" \ --registration-token "REGISTRATION_TOKEN" \ --description "docker-runner" \ --executor "docker" \ --docker-image centos:latest

Troubleshooting Job Execution

A common issue encountered during registration is the "stuck job" error. This typically occurs when a runner is registered with specific tags, but the CI/CD job defined in the project does not include matching tags.

To resolve this, navigate to the GitLab Web UI:

1. Go to the project's Settings.
2. Select CI/CD.
3. Expand the Runners section.
4. Ensure the option "Indicates whether this runner can pick up jobs without tags" is checked.

Uninstallation and System Cleanup

If a complete removal of the GitLab Runner is required, several steps must be taken to ensure all binaries, configurations, and processes are purged from the CentOS system.

1. Uninstall the RPM package:
   bash sudo yum uninstall gitlab-runner-10.0.0-1

2. Remove the GitLab directory:
   bash sudo rm -rf /var/opt/gitlab

3. Terminate all active GitLab processes:
   bash pkill -f gitlab

4. Remove all installation-related directories:
   bash sudo rm -rf /opt/gitlab sudo rm -rf /etc/gitlab sudo rm -rf /var/opt/gitlab

Analysis of Deployment Methodologies

The deployment of GitLab Runner on CentOS 7 presents a spectrum of complexity, ranging from the streamlined yum installation to the highly manual TLS-secured configuration. The choice of method is dictated by the security requirements of the organization and the specific executor being utilized.

While the standard repository method is ideal for general-purpose runners, the binary-based installation offers superior flexibility for heterogeneous environments. The integration of TLS-based configurations is a necessity for modern DevSecOps practices, ensuring that the communication between the runner and the containerized environments is protected against interception.

Crucially, the management of user permissions through the sudoers file remains a pivot point for both security and functionality. Over-provisioning permissions can introduce vulnerabilities, while under-provisioning can lead to the aforementioned "stuck jobs" or failed build processes. Therefore, a successful deployment requires a balanced approach to identity and access management (IAM) within the Linux subsystem, ensuring that the gitlab-runner user has exactly the level of access required to facilitate the CI/CD lifecycle without compromising the integrity of the host CentOS 7 server.

Sources

1. Installing gitlab-runner v14.0.0 with TLS on CentOS7
2. How to Install GitLab Runner on CentOS/RHEL/Fedora
3. GitLab Runner GitHub Repository
4. GitLab Documentation: Install GitLab Runner on Linux Manually