Decommissioning GitLab Runner Ecosystems and GitLab Server Environments

The lifecycle management of CI/CD infrastructure requires not only the ability to provision and scale resources but also the capacity to decommission them cleanly. Removing GitLab Runner—the lightweight application that works with GitLab CI/CD to run jobs—is a multi-faceted process that varies significantly depending on the host operating system, the method of installation, and whether the intent is to merely unregister a runner from a GitLab instance or to completely purge the software from the underlying hardware. Failure to execute these steps in the correct sequence can lead to orphaned services, lingering configuration files, or "FATAL" errors where the system attempts to remove service files that no longer exist. This technical analysis provides the procedural rigor required to manage the removal of GitLab Runner and the broader GitLab server environment across Ubuntu, macOS, and various service-oriented architectures.

The Distinction Between Unregistering and Uninstalling

A critical distinction must be established before any command is executed: the difference between unregistering a runner from the GitLab server and uninstalling the runner software from the local machine.

Unregistering is a logical operation performed within the runner's own CLI or via the GitLab UI. When a runner is unregistered, the connection between the local agent and the GitLab instance is severed. This is essential for security and resource management, as it prevents the runner from picking up new jobs. However, unregistering does not remove the binary from the disk, nor does it stop the service if it is running as a system daemon.

Uninstalling is a physical operation. It involves stopping the service, removing the binary, deleting the configuration files, and potentially purging the user accounts created specifically for the runner's execution.

To ensure a clean decommissioning, one must often perform both operations. If a runner is uninstalled without being unregistered, the GitLab server may still show the runner as "online" or "available" until the heartbeat timeout is reached, leading to ghost entries in the GitLab administration panel.

Systematic Removal on Ubuntu 22.04 and Linux Distributions

On Linux systems, particularly Ubuntu 22.04, GitLab Runner is typically managed as a system service. The removal process must be handled with a specific order of operations to prevent service errors or permission conflicts.

Service Termination and Service-Level Removal

The first stage involves stopping the active process and telling the system manager to forget the service.

Stop the runner service.
sudo gitlab-runner stop
This command halts the execution of the runner, ensuring that no active CI/CD jobs are interrupted mid-stream.
Uninstall the service.
sudo gitlab-runner uninstall
This instructs the runner application to remove itself from the system's service manager (such as systemd).
Reload the system daemon.
sudo systemctl daemon-reload
After the service is uninstalled, the system's service manager needs to refresh its internal state to acknowledge that the gitlab-runner.service file is gone.

Filesystem Purge and User Management

Once the service is no longer active in the system's eyes, the physical files and the dedicated user must be removed.

Remove the binary.
sudo rm -rf /usr/local/bin/gitlab-runner
This deletes the executable file itself.
Delete the dedicated runner user.
sudo userdel gitlab-runner
GitLab Runner often runs under a specific user account for security isolation. Removing this user is necessary to maintain system hygiene.
Remove the home directory and configuration data.
sudo rm -rf /home/gitlab-runner/
This clears out any local data, including the config.toml file and cached files associated with the runner user.

Addressing macOS Uninstallation Failures

Users operating on macOS may encounter specific failures during the uninstallation process. A documented issue exists where running the standard uninstall command results in a fatal error.

The LaunchAgents Error

When a user executes gitlab-runner uninstall on macOS, they may encounter the following error:

FATAL: Failed to uninstall gitlab-runner: remove /Users/(...)/Library/LaunchAgents/gitlab-runner.plist: no such file or directory

This error occurs when the runner's service-level configuration (the .plist file used by macOS to manage background agents) has already been removed or was never correctly registered in the expected directory. This creates a state of inconsistency where the runner believes it should manage a service file that the OS cannot find.

Troubleshooting macOS Runner Removal

To resolve this, the user must manually ensure that the LaunchAgents directory is cleaned or bypass the automated uninstaller. If the automated command fails, the user must manually inspect the ~/Library/LaunchAgents/ directory and remove any remnants of gitlab-runner.plist.

Comprehensive GitLab Server Decommissioning

In scenarios where the entire GitLab instance (the server itself) must be removed, a much more aggressive set of commands is required. This is typically done using the gitlab-ctl command-line tool provided by the GitLab Omnibus package.

Data Destruction and Cleanup

The following table outlines the critical stages of a full GitLab server removal:

Command	Impact	Consequence
`sudo gitlab-ctl uninstall`	Stops all GitLab services	All running GitLab processes are terminated immediately.
`sudo gitlab-ctl cleanse`	Deletes all local configuration and logs	All configuration, logs, and local variable data are permanently deleted.
`sudo gitlab-ctl remove-accounts`	Removes user accounts	All local user accounts associated with the GitLab installation are purged.

Warning: The gitlab-ctl cleanse command is extremely destructive. It is designed to wipe all local configuration, logs, and variable data. It is highly recommended to have a full backup before proceeding.

Package and Repository Removal

After the services and data are wiped, the software package must be removed using the system package manager. For Debian-based systems like Ubuntu, use dpkg.

Uninstall the package.
sudo dpkg -P gitlab-ce (for Community Edition)
sudo dpkg -P gitlab-ee (for Enterprise Edition)
Remove residual directories.
rm -rf /opt/gitlab*
rm -rf /var/opt/gitlab*
rm -rf /etc/gitlab*
rm -rf /var/log/gitlab*
These directories contain the core application files, data, configuration, and logs that the package manager might not have fully purged.
Clean up APT sources.
rm /etc/apt/sources.list.d/runner_gitlab-runner.list*
rm /etc/apt/sources.list.d/gitlab_gitlab-ee.list*
rm /etc/apt/sources.list.d/gitlab_gitlab-ce.list*
Finally, refresh the package lists to ensure the system no longer attempts to contact the GitLab repositories during updates.
apt update

Advanced Runner Management and Registration Commands

For administrators who need to manage runners without full uninstallation, GitLab provides a suite of commands within the gitlab-runner CLI.

Unregistering Specific Runners

Unregistering is the preferred method for removing a single runner from a GitLab instance. This is done by communicating with the GitLab API.

To list all currently configured runners to find the necessary tokens or names:
gitlab-runner list
To unregister a runner by its URL and authentication token:
gitlab-runner unregister --url "http://gitlab.example.com/" --token t0k3n
To unregister a runner by its name:
gitlab-runner unregister --name test-runner
Note: If multiple runners share the same name, only the first one found will be removed.
To unregister all runners configured on the machine:
gitlab-runner unregister --all-runners

Token Management and Security

If a runner's token has expired or been compromised, the reset-token command is used. This is vital for maintaining the security of the CI/CD pipeline.

Resetting a token by name:
gitlab-runner reset-token --name test-runner
Resetting a token using a Personal Access Token (PAT) and the runner name:
gitlab-runner reset-token --name test-runner --pat PaT
Resetting a token using a PAT, the GitLab URL, and a specific Runner ID:
gitlab-runner reset-token --url "https://gitlab.example.com/" --id 12345 --pat PaT
Resetting all attached runners:
gitlab-runner reset-token --all-runners

Service Command Reference

The following table provides a quick reference for standard service-level management commands used during the installation and maintenance phases.

Command	Purpose
`gitlab-runner install`	Installs the runner as a system or user service.
`gitlab-runner uninstall`	Stops and uninstalls the runner as a service.
`gitlab-runner start`	Starts the runner service.
`gitlab-runner stop`	Stops the runner service.
`gitlab-runner restart`	Restarts the runner service.
`gitlab-runner status`	Displays the current status of the runner service.

Comprehensive Command Catalog

The GitLab Runner CLI is an extensive tool. Beyond basic service management, it includes specialized commands for various operational needs.

Primary Commands

register: Used to add a new runner to a GitLab instance.
run: Runs the multi-runner service.
run-single: Starts a single runner.
verify: Validates all currently registered runners.
help or -h: Displays the command help menu.
--version or -v: Prints the version of the GitLab Runner.

Global Options and Advanced Configurations

When executing commands, several global options can modify behavior:

--debug: Enables debug mode for troubleshooting.
--log-level: Sets the verbosity of logs (options include debug, info, warn, error, fatal, panic).
--log-format: Defines the output format (options include runner, text, json).
--config: Allows the user to specify a custom configuration file path.
--service: Allows for specifying a custom service name.
--user: (Windows/Super-user) Allows dropping privileges for shell executor builds.

Internal and Specialized Commands

Several commands are intended for internal use or specific executor types:

fleeting: Used to manage fleeting plugins.
artifacts-downloader: Internal command to download and extract build artifacts.
artifacts-uploader: Internal command to upload build artifacts.
cache-archiver: Internal command to create cache artifacts.
cache-extractor: Internal command to extract cache artifacts.
cache-init: Internal command to change permissions for cache paths.
read-logs: Used by the Kubernetes executor to read job logs.
proxy-exec: Internal command for execution proxying.
health-check: Checks the health of a specific address.
wrapper: Starts the multi-runner service wrapped with a gRPC manager server.

Technical Analysis of the Decommissioning Lifecycle

The process of uninstalling GitLab Runner is not a singular event but a layered transition from active service to total system erasure. A successful decommissioning requires a synchronized approach between the application logic (unregistering), the operating system service manager (stopping and uninstalling), and the filesystem (purging binaries and data).

The complexity of this task is compounded by the different ways GitLab Runner interacts with the host. In a Docker-based executor environment, the runner might be managing containers that require their own cleanup. In a shell-based executor environment, the runner operates directly on the host, meaning the userdel and rm -rf steps are critical to prevent leaving sensitive build data or orphaned user permissions on the system.

Furthermore, the existence of the "FATAL" error on macOS highlights a vulnerability in the automation of uninstallation. When the CLI attempts to perform cleanup on a service that is partially unconfigured, the lack of idempotency in the uninstallation script can lead to failure. Therefore, manual intervention and a deep understanding of the underlying service manager (systemd for Linux, LaunchAgents for macOS) is mandatory for any professional DevOps engineer.

Ultimately, the goal of a clean uninstall is to return the host system to its original state, ensuring that no residual configuration prevents the installation of future versions or different CI/CD tools. This requires the methodical application of the removal commands, starting from the highest level of service abstraction down to the lowest level of the filesystem.