gitlab-ctl

Display the status of every service

$ sudo gitlab-ctl status

$ sudo gitlab-ctl status [nginx]

$ sudo gitlab-ctl restart

$ sudo gitlab-ctl restart [nginx]

$ sudo gitlab-ctl tail

$ sudo gitlab-ctl tail [nginx]

$ sudo gitlab-ctl kill [nginx]

$ sudo gitlab-ctl reconfigure

gitlab-ctl [global options] <command> [command options/arguments]

Examples:
gitlab-ctl reconfigure
gitlab-ctl status
gitlab-ctl start nginx

reconfigure
    Applies configuration changes from /etc/gitlab/gitlab.rb and reconfigures all GitLab services.

start [service]
    Starts all GitLab services, or a specific service like nginx, postgresql, sidekiq.

stop [service]
    Stops all GitLab services, or a specific service.

restart [service]
    Restarts all GitLab services, or a specific service.

status
    Displays the current running status of all GitLab services.

tail [service]
    Continuously outputs log entries for all GitLab services or a specific service (e.g., nginx, unicorn).

console
    Opens an interactive Ruby on Rails console for the GitLab application.

psql
    Opens an interactive PostgreSQL console for the GitLab database.

redis-cli
    Opens an interactive Redis command-line interface for GitLab's Redis instance.

backup-etc
    Creates a backup of GitLab configuration files and directories.

upgrade
    Performs tasks related to GitLab upgrades, often followed by reconfigure.

--help, -h
    Displays general help information or help for a specific subcommand.

--verbose
    Enables verbose output during command execution, showing more details.

--debug
    Enables debug output, providing even more detailed information, useful for troubleshooting.

gitlab-ctl is the primary command-line interface for managing a GitLab Omnibus installation. It provides a unified way to control various services like Nginx, PostgreSQL, Redis, Unicorn, and Sidekiq, which are integral components of GitLab.

This utility simplifies complex administrative tasks such as applying configuration changes, starting or stopping services, checking their status, and tailing logs. It abstracts away the underlying complexities of managing individual service processes, making GitLab administration more straightforward for system administrators. Key functions include reconfigure for applying changes from /etc/gitlab/gitlab.rb, start, stop, restart, status for service control, tail for log monitoring, and console, psql, redis-cli for advanced debugging and database interactions. gitlab-ctl is essential for maintaining a healthy and up-to-date GitLab instance packaged via the Omnibus installer.

Privilege Requirement: Most gitlab-ctl commands require root or sudo privileges to execute successfully due to their system-wide impact on services and configurations.
Omnibus Specific: This command is designed for and primarily used with GitLab Omnibus package installations. It is generally not applicable or fully functional for source installations of GitLab.
Configuration Changes: Many configuration changes made in /etc/gitlab/gitlab.rb will not take effect until gitlab-ctl reconfigure is run. Forgetting this step is a common troubleshooting point.
Service Disruptions: Commands like stop or restart will temporarily disrupt GitLab services, making them unavailable to users. Plan execution during maintenance windows.

The primary configuration file for GitLab Omnibus installations is /etc/gitlab/gitlab.rb. Most system-level settings and service configurations are managed through this file, with gitlab-ctl reconfigure applying the changes.

gitlab-ctl reconfigure executes Chef recipes. It reads the settings from gitlab.rb and compiles them into a Chef run list, which then configures the various services and components of GitLab.

GitLab services managed by gitlab-ctl typically write their logs to /var/log/gitlab/. The gitlab-ctl tail command provides a convenient way to monitor these logs in real-time.

The gitlab-ctl command emerged as a cornerstone of the GitLab Omnibus package, which was introduced to simplify the installation, configuration, and management of GitLab. Prior to Omnibus, deploying GitLab from source was a complex process requiring manual setup of various components like Nginx, PostgreSQL, Redis, and Ruby applications. gitlab-ctl was developed to abstract these complexities, leveraging Chef Solo for idempotent configuration management and providing a user-friendly interface for common administrative tasks. Its introduction significantly lowered the barrier to entry for self-hosting GitLab, making it accessible to a wider audience by providing a robust, all-in-one package with a consistent management interface.

gitlab-rails(8), gitlab-rake(8), systemctl(1), chef-solo(8)