Консоль Rails в GitLab — руководство

Быстрая навигация

Запуск консоли
Базовое использование
Распространённые задачи
Запуск Ruby-скриптов через runner
Политика безопасности и восстановление после ошибок
Краткое резюме

Важно: консоль даёт полный доступ к данным. Неправильные команды могут привести к необратимой потере данных.

Что такое консоль Rails в GitLab

Консоль Rails запускает интерактивную среду Ruby on Rails в контексте вашей установки GitLab. Она позволяет выполнять Ruby-код, обращаться к моделям ActiveRecord и напрямую изменять записи в базе. Определение: Active Record — ORM-паттерн, который отображает строки БД в объекты Ruby.

Кому нужна эта инструкция: администраторы GitLab, инженеры поддержки, инженеры DevOps, ответственные за восстановление и диагностику.

Запуск консоли

Способ запуска зависит от типа установки GitLab.

Omnibus-пакет (пакетный установщик):

$ sudo gitlab-rails console

Если GitLab был установлен из исходников вручную:

$ sudo -u git -H bundle exec rails console -e production

В Kubernetes (cloud-native) подключитесь к Pod toolbox через kubectl:

$ kubectl --namespace gitlab exec -it toolbox -- /srv/gitlab/bin/rails console

В версиях GitLab старше 14.2 вместо toolbox может присутствовать Pod task-runner.

Консоль может загружаться несколько секунд. Она выводит версии Ruby, GitLab, GitLab Shell и PostgreSQL, после чего показывает приглашение:

$ sudo gitlab-rails console

Ruby: ruby 2.7.5p203 (2021-11-24 revision f69aeb8314) [x86_64-linux]

GitLab: 15.0.0 (8a186dedfc1) FOSS

GitLab Shell: 14.3.0

PostgreSQL: 12.10

————————————————————[ booted in 22.48s ]

Loading production environment (Rails 6.1.4.7)

irb(main):001:0>


Когда вы видите приглашение, можно вводить Ruby-команды.

## Базовое использование

Консоль предоставляет доступ к объектной модели GitLab. Понимание Ruby и основ Rails ускорит работу.

Пример: получение пользователя по username:

$ demo = User.find_by_username(“demo”)


Обычно объекты можно инспектировать через атрибуты:

$ pp demo.attributes

{“id”=>1, “email”=>”demo@example.com”, …}


Получение конкретного свойства:

$ demo.email

demo@example.com


Поиск нескольких записей:

$ admins = User.where(admin: true).where(‘email like ?’, ‘%@example.com’)


Изменение свойств объекта и сохранение:

$ demo.email = “example@example.com” $ demo.save


Если валидации мешают и нужно принудительно сохранить (использовать осторожно):

$ demo.save!(validate: false)


Используйте этот режим только для расследования проблем, когда UI или API отказываются принимать корректные изменения.

## Распространённые задачи

Ниже — часто встречающиеся операции с примерами команд.

### Узнать доступные методы объекта

Если вы не уверены, какие методы есть у модели, можно перечислить их:

$ User.methods


Вместо полного списка можно отфильтровать по шаблону:

$ Project.methods.grep(/find/)


Например, чтобы получить проект по его пути:

$ Project.find_by_full_path(“/user/project”)


### Получить проект и его задачи (issues) и merge request

$ project = Project.find_by_full_path(“/user/project”)

$ project.issues.all

$ project.issues.first

$ project.merge_requests.find_by(iid: 10)


### Получить CI pipeline

Объект Pipeline находится в namespace `Ci`:

$ pipeline = Ci::Pipeline.find(100)

$ jobs = pipeline.builds


### Сброс пароля администратора

$ user = User.find_by_username(“demo”) $ user.password = “abc123” $ user.password_confirmation = “abc123” $ user.save


### Сделать проект только для чтения

$ project = Project.find_by_full_path(“/user/project”) $ project.repository_read_only = true $ project.save


### Запустить расписание pipeline вручную

$ schedule = Ci::PipelineSchedule.find_by(id: 10) $ user = User.find_by_username(“demo”) $ Ci::CreatePipelineService.new(schedule.project, user, ref: schedule.ref).execute!(:schedule, ignore_skip_ci: true, save_on_errors: false, schedule: schedule)


Команда создаст новый pipeline по расписанию и запустит его.

### Включить Feature Flag

Feature Flags часто доступны только через консоль:

$ Feature.enable(:certificate_based_clusters)


Проверить состояние флага:

$ Feature.enabled?(:certificate_based_clusters)

=> true


Отключение:

$ Feature.disable(:certificate_based_clusters)


### Отправить тестовое письмо

$ Notify.test_email(“example@example.com”, “Test subject”, “Test body”).deliver_now


Письмо отправится через тот же механизм, что и системные уведомления GitLab.

## Запуск Ruby-скриптов через Rails Runner

Интерактивная сессия не всегда обязательна. `gitlab-rails runner` выполняет код в контексте приложения и завершает процесс.

Пример однострочной команды:

$ sudo gitlab-rails runner “puts User.find_by_username(‘demo’).email”


Запуск скрипта из файла:

$ sudo gitlab-rails runner /scripts/gitlab-rails-script.rb


Важно: runner всегда запускается от пользователя `git:git`. Файлы должны быть доступны этому пользователю. Неправильный путь будет интерпретирован как код и вызовет синтаксическую ошибку.

Для справки запустите:

Run ‘rails runner -h’ for help


## Мини‑методология: как безопасно работать в консоли

1. Никогда не работайте в консоли на продакшне без резервной копии БД.
2. Используйте read-only запросы сначала (select), затем операции изменения.
3. Оборачивайте критичные изменения в транзакции, если поддерживается.
4. Тестируйте команды в тестовой/стейдж среде перед применением в продакшн.
5. Логируйте все шаги и сохраняйте снимок окружения (версии ПО).

Пример шаблона проверки перед изменением:

- Сохраните идентификаторы объектов
- Выполните SELECT и убедитесь, что выборка корректна
- Выполните изменение на ограниченном наборе
- Проверьте эффекты, затем масштабируйте

## Политика доступа и безопасность

- Консоль даёт привилегированный доступ; только доверенные администраторы должны иметь к ней доступ.
- Все действия через консоль обходят многие защитные механизмы.
- Включение экспериментальных функций и прямые правки данных не покрываются поддержку GitLab и могут привести к нестабильности.

Рекомендации по защите:

- Ограничьте SSH-доступ к узлам, где можно запустить консоль.
- Включите аудит командной оболочки (bash history, централизованный лог).
- Используйте отдельную учётную запись администратора для операций в консоли.
- Делайте регламентированные инструкции и чек‑листы для типовых операций.

## Инструменты для предотвращения ошибок

- Выполняйте сложные изменения в транзакции:

ActiveRecord::Base.transaction do # изменения raise ActiveRecord::Rollback unless success_condition end


- Используйте `save!` с обработкой исключений, чтобы явно фиксировать неуспехи.
- Создавайте временные метки (например, логируйте объект и dump перед изменением).

## Runbook при критической ошибке

1. Остановите автоматические процессы, которые могут модифицировать данные (CI, cron).
2. Сделайте консистентный бэкап БД и приложений.
3. Если команда привела к удалению/повреждению, попытайтесь откатить с помощью транзакции/восстановления из бэкапа.
4. Проанализируйте журналы и зафиксируйте точное время и команды.
5. Уведомьте команду инцидента и обеспечьте коммуникацию с пользователями при необходимости.
6. После восстановления оформите постмортем и обновите SOP.

Критерии успешного восстановления:

- Восстановлены ключевые репозитории и их метаданные
- Пользователи снова могут аутентифицироваться
- CI/CD пайплайны восстанавливают работоспособность

## Контрольные списки по ролям

Администратор (операция с консолью):

- Проверить, что есть свежая бэкап-копия БД
- Проверить версии GitLab и Ruby
- Записать команду в журнал действий
- Выполнить команду в тестовом окружении
- Повторить в продакшне

DevOps-инженер (развёртывание и безопасность):

- Ограничить доступ по SSH
- Настроить аудит и централизованные логи
- Обеспечить доступность инструментов отката и бэкапов

Инженер поддержки (диагностика):

- Начать с чтения данных (SELECT)
- Не менять данные без согласования с админом
- Составить отчёт с шагами воспроизведения

## Когда консоль не подходит (примеры неудач)

- Массовые изменения данных лучше делать через миграции или API с контролем задач.
- Автоматизированные регулярные правки — через CI скрипты и job‑шаблоны с возможностью отката.
- Если требуется журналируемость и доказуемость операций — предпочтительнее API с аудитом.

## Практические примеры и шаблоны

1) Поиск и массовое исправление email для тестовых доменов:

users = User.where(‘email LIKE ?’, ‘%@example.com’) users.find_each do |u| u.update!(email: “#{u.id}@example.com”) end


2) Включение флага для группы проектов:

Group.find_each do |g| g.projects.each do |p|

Feature.enable(:some_flag) if p.id == 123

end end


3) Безопасное изменение с транзакцией:

ActiveRecord::Base.transaction do project = Project.find_by_full_path(“/user/project”) project.repository_read_only = true project.save! end


## Edge cases и частые ошибки

- Ошибка: "Permission denied" при запуске runner — проверьте права и владельца скрипта (git:git).
- Ошибка: невалидные пути к файлам — runner воспринимает несуществующий путь как код.
- Последовательность версий Ruby/GitLab/PG может привести к несовместимости объектов; перед редкими операциями фиксируйте версии.

## Совместимость и миграции

- Перед крупными изменениями проверьте встроенные миграции базы данных GitLab.
- Обновления GitLab могут изменить поведение внутренних моделей — избегайте зависимостей от приватных методов.

## Краткий чеклист перед началом работы

- [ ] Есть актуальный бэкап базы данных
- [ ] Понимание цели и ожидаемого результата
- [ ] Тестирование в staging
- [ ] Журналирование команд и результатов
- [ ] Наличие плана отката

## Краткое резюме

Консоль Rails в GitLab — незаменимый инструмент для администратора при диагностике и аварийном вмешательстве. Она позволяет выполнять как простые запросы, так и сложные операции управления. Вместе с тем она несёт риск, поэтому работа должна быть плановой, с бэкапами, и ограниченной доверенными пользователями.

Важно: оформляйте все нестандартные правки в виде задач с описанием и постмортем при необходимости.

## Глоссарий

- Active Record: ORM, сопоставляет таблицы БД с объектами Ruby.
- Runner: инструмент для выполнения Ruby-скриптов в контексте GitLab.
- Feature Flag: переключатель функции на уровне приложения.


---

![Краткая проверка безопасности](/files/e749249c-f221-4b27-8952-b844b91722ce.jpg)

Изображение повторяет логотип GitLab для визуальной идентификации инструкции.