If you’re like most developers, you probably use GitLab for its excellent code management and collaboration features. But did you know that GitLab also has a powerful Rails console? In this article, we’ll show you how to use the Rails console to administer your GitLab instance. GitLab is a great tool for managing code, but it can be difficult to manage complex deployments and configurations. The Rails console makes it easy to manage these tasks by providing a user-friendly interface for performing advanced administration tasks. In this article, we’ll show you how to use the Rails console to: Configure your GitLab instance Manage your codebase and deployments Monitor your application’s performance ..

GitLab’s Rails console provides an interactive terminal that lets you directly manipulate data in your GitLab instance. You can use it to extract information, troubleshoot problems, and perform advanced administration tasks that aren’t supported in the GitLab web UI or API.

To access the console you must be running your own self-managed GitLab server. You’ll need superuser privileges on the machine that hosts your environment. The console provides unimpeded control over GitLab and your data so only trusted administrators should be allowed to use it. Actions can override normal safeguards and cause unprompted data destruction.

Starting the Console

The method used to start the console depends on the type of GitLab installation you’re running. Omnibus distributions installed from a package manager support the following command:

Use this alternative if you’ve manually installed GitLab from source:

The console’s also available to cloud-native GitLab instances running in Kubernetes. Use Kubectl to attach to GitLab’s toolbox Pod and start a console session:

GitLab versions older than 14.2 will have a task-runner Pod instead of toolbox. Substitute task-runner into the command shown above if you’re running one of these releases.

The Rails console can take several seconds to start up. It’ll display a summary of your Ruby, GitLab, and PostgreSQL versions before dropping you to a terminal prompt.

You can start issuing Ruby commands when you see the prompt appear.

Basic Usage

The console provides access to GitLab’s Ruby on Rails environment. In-scope objects let you fetch, update, and query data in your GitLab database. A basic understanding of Ruby and Rails will help you to get started.

Rails uses the Active Record pattern to provide static data mapping methods on objects. You can call the following method to retrieve a user by their username:

You can view the properties of the retrieved object by inspecting its attributes:

To retrieve a specific property, access it by name:

You can use Rails methods to conveniently fetch multiple object instances that match a query:

This fetches all the example.com users with GitLab administrator permissions.

You can change the properties of an object instance by assigning new values and calling save:

The save method will check the object’s in a valid state before saving it to the database. You can explicitly disable validation in situations where you want to force a particular change to apply:

This should only be used to investigate issues where the GitLab web UI or API is unexpectedly rejecting data.

Common Tasks

The GitLab Rails console has limitless applications as you can work with any aspect of your GitLab instance. Here are some useful operations to get you started.

Discover Methods Available On An Object

The console experience can be daunting to newcomers, especially if you don’t have much familiarity with Rails. Documentation on the console is relatively sparse but you can discover functionality by retrieving the method list associated with each object:

You can combine this with grep to quickly filter to methods with a particular root:

This reveals you can fetch a project by its path with the following command:

Retrieve a Project With Its Issues and Merge Requests

First use the Project object to get the project by matching on a unique attribute such as its ID, path, or URL:

Now you can access the project’s issues and merge requests via its relation properties:

Retrieve a CI Pipeline

The Pipeline object is nested inside the CI namespace:

Reset an Admin’s Password

The console can rescue you if you ever get locked out of your account. Retrieve the affected user object and then reset its password:

Make a Project Read-Only

GitLab supports read-only projects that keep the repository accessible but prevent modifications from being made. Read-only mode has to be enabled using the console:

Manually Run a Pipeline Schedule

Scheduled pipelines can be executed immediately using the console. This can sometimes help to debug issues which aren’t fully reported in the UI and API.

First retrieve the PipelineSchedule object:

Next fetch the user you want to execute the pipeline as:

Now use this command to start a run through the schedule:

It creates a new pipeline from the schedule and commences its execution.

Enable Feature Flags

Some pre-release GitLab features are gated behind feature flags. Flags are also sometimes used to permit temporary reactivation of deprecated capabilities.

The console is the only mechanism by which feature flags can be enabled. Pass the ID of a feature flag to the Feature.enable() function:

The change applies immediately without restarting GitLab. This example reactivates support for certificate-based Kubernetes clusters in GitLab 15.0.

You can check whether a flag’s enabled with a Feature.enabled?() call:

To disable a feature flag, pass its ID to the Feature.disable() method:

Test Email Delivery

The console lets you directly send test messages to verify your outbound email system is working:

The email will be sent immediately using the same mechanism as messages created by GitLab application functions.

Running Ruby Scripts With the Rails Runner

An interactive console session isn’t always necessary. The Rails Runner is an alternative which makes it easier to run Ruby scripts in the context of your GitLab environment.

Use the gitlab-rails runner command to execute some Ruby code. Your script can reference the same GitLab variables and objects that are available to a Rails console session.

Rails will run the script you provide and then terminate the process. The example shown above emits the email address of the GitLab user called demo. This alternative runs Ruby code provided as a file:

Scripts saved as Ruby files need to be accessible to the Unix git user. GitLab Rails always executes as git:git so scripts owned by other users could produce an error. Invalid file paths will be interpreted as Ruby code to run, producing a syntax error that can mask the true problem:

Summary

The GitLab Rails console is a powerful utility for directly interacting with your GitLab instance. It can be an invaluable debugging tool when you’re experiencing problems with your installation. The console also lets you script admin tasks using plain Ruby code, instead of relying on the GitLab API. Some operations such as feature flag enablement can only be achieved with the console.

With power comes responsibility. The console is capable of ignoring guardrails and accepting operations in contexts which they’re not designed for. Incorrect use could cause data loss and unexpected behavior. By using the console you’re lifting the lid on GitLab’s codebase and its internal operations. The available methods and their effects lack a support guarantee and could change without warning.