Comment démarrer avec la console Rails de GitLab pour l’administration avancée
La console Rails de GitLab fournit un terminal interactif qui vous permet de manipuler directement les données dans votre instance GitLab. Vous pouvez l’utiliser pour extraire des informations, résoudre des problèmes et effectuer des tâches d’administration avancées qui ne sont pas prises en charge dans l’interface utilisateur Web ou l’API GitLab.
Pour accéder à la console, vous devez exécuter votre propre serveur GitLab autogéré. Vous aurez besoin des privilèges de superutilisateur sur la machine qui héberge votre environnement. La console offre un contrôle sans entrave sur GitLab et vos données, de sorte que seuls les administrateurs de confiance doivent être autorisés à l’utiliser. Les actions peuvent outrepasser les protections normales et provoquer une destruction de données spontanée.
Sommaire
Démarrage de la console
La méthode utilisée pour démarrer la console dépend du type d’installation de GitLab que vous exécutez. Les distributions Omnibus installées à partir d’un gestionnaire de packages prennent en charge la commande suivante :
$ sudo gitlab-rails console
Utilisez cette alternative si vous avez installé manuellement GitLab à partir de la source :
$ sudo -u git -H bundle exec rails console -e production
La console est également disponible pour les instances GitLab natives du cloud exécutées dans Kubernetes. Utilisez Kubectl pour vous connecter à GitLab toolbox
Pod et démarrez une session de console :
$ kubectl --namespace gitlab exec -it toolbox -- /srv/gitlab/bin/rails console
Les versions de GitLab antérieures à 14.2 auront un task-runner
Pod au lieu de toolbox
. Remplaçant task-runner
dans la commande ci-dessus si vous exécutez l’une de ces versions.
La console Rails peut mettre plusieurs secondes à démarrer. Il affichera un résumé de vos versions Ruby, GitLab et PostgreSQL avant de vous déposer à une invite de terminal.
$ 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>
Vous pouvez commencer à émettre des commandes Ruby lorsque vous voyez l’invite apparaître.
Utilisation de base
La console permet d’accéder à l’environnement Ruby on Rails de GitLab. Les objets dans la portée vous permettent de récupérer, de mettre à jour et d’interroger des données dans votre base de données GitLab. Une compréhension de base de Ruby et Rails vous aidera à démarrer.
Rails utilise le modèle Active Record pour fournir des méthodes de mappage de données statiques sur les objets. Vous pouvez appeler la méthode suivante pour récupérer un utilisateur par son nom d’utilisateur :
$ demo = User.find_by_username("demo") # <User id:1 @demo>
Vous pouvez afficher les propriétés de l’objet récupéré en inspectant son attributes
:
$ pp demo.attributes {"id"=>1, "email"=>"demo@example.com", ...
Pour récupérer une propriété spécifique, accédez-y par son nom :
$ demo.email demo@example.com
Vous pouvez utiliser les méthodes Rails pour récupérer facilement plusieurs instances d’objet correspondant à une requête :
$ admins = User.where(admin: true).where('email like ?', '%@example.com')
Cela récupère tous les example.com
utilisateurs avec des autorisations d’administrateur GitLab.
Vous pouvez modifier les propriétés d’une instance d’objet en affectant de nouvelles valeurs et en appelant save
:
$ demo.email = "example@example.com" $ demo.save
La save
La méthode vérifiera que l’objet est dans un état valide avant de l’enregistrer dans la base de données. Vous pouvez explicitement désactiver la validation dans les situations où vous souhaitez forcer l’application d’une modification particulière :
$ demo.save!(validate: false)
Cela ne doit être utilisé que pour enquêter sur les problèmes où l’interface utilisateur Web ou l’API GitLab rejette des données de manière inattendue.
Tâches communes
La console GitLab Rails a des applications illimitées car vous pouvez travailler avec n’importe quel aspect de votre instance GitLab. Voici quelques opérations utiles pour vous aider à démarrer.
Découvrir les méthodes disponibles sur un objet
L’expérience de la console peut être intimidante pour les nouveaux arrivants, surtout si vous n’êtes pas très familiarisé avec Rails. La documentation sur la console est relativement clairsemée mais vous pouvez découvrir les fonctionnalités en récupérant la liste des méthodes associées à chaque objet :
$ User.methods [:before_add_for_closed_issues, :before_add_for_closed_issues=, :after_add_for_closed_issues, ...]
Vous pouvez combiner cela avec grep
pour filtrer rapidement les méthodes avec une racine particulière :
$ Project.methods.grep(/find/) [:find_by_runners_token, :find_by_url, :find_by_full_path, ...]
Cela révèle que vous pouvez récupérer un projet par son chemin avec la commande suivante :
$ Project.find_by_full_path("/user/project")
Récupérer un projet avec ses problèmes et ses demandes de fusion
Utilisez d’abord le Project
objet pour obtenir le projet en faisant correspondre un attribut unique tel que son ID, son chemin ou son URL :
$ project = Project.find_by_full_path("/user/project")
Vous pouvez désormais accéder aux problèmes du projet et aux demandes de fusion via ses propriétés de relation :
# Get all issues $ project.issues.all # Get the first issue $ project.issues.first # Get a specific merge request by its project-level ID $ project.merge_requests.find_by(iid: 10)
Récupérer un pipeline CI
La Pipeline
l’objet est imbriqué dans le CI
espace de noms :
# Get the pipeline with ID 100 $ pipeline = Ci::Pipeline.find(100) # Get builds (jobs) associated with the pipeline $ jobs = pipeline.builds
Réinitialiser le mot de passe d’un administrateur
La console peut vous sauver si jamais vous êtes bloqué sur votre compte. Récupérez l’objet utilisateur concerné, puis réinitialisez son mot de passe :
$ user = User.find_by_username("demo") $ user.password = "abc123" $ user.password_confirmation = "abc123" $ user.save
Rendre un projet en lecture seule
GitLab prend en charge les projets en lecture seule qui maintiennent le référentiel accessible mais empêchent les modifications d’être apportées. Le mode lecture seule doit être activé à l’aide de la console :
$ project = Project.find_by_full_path("/user/project") $ project.repository_read_only = true $ project.save
Exécuter manuellement une planification de pipeline
Les pipelines planifiés peuvent être exécutés immédiatement à l’aide de la console. Cela peut parfois aider à déboguer des problèmes qui ne sont pas entièrement signalés dans l’interface utilisateur et l’API.
Récupérez d’abord le PipelineSchedule
objet:
$ schedule = Ci::PipelineSchedule.find_by(id: 10)
Récupérez ensuite l’utilisateur sous lequel vous souhaitez exécuter le pipeline :
$ user = User.find_by_username("demo")
Utilisez maintenant cette commande pour démarrer une exécution via le programme :
$ Ci::CreatePipelineService.new(schedule.project, user, ref: schedule.ref).execute!(:schedule, ignore_skip_ci: true, save_on_errors: false, schedule: schedule)
Il crée un nouveau pipeline à partir de la planification et commence son exécution.
Activer les indicateurs de fonctionnalité
Certaines fonctionnalités de pré-version de GitLab sont protégées par des indicateurs de fonctionnalité. Les drapeaux sont également parfois utilisés pour permettre la réactivation temporaire de capacités obsolètes.
La console est le seul mécanisme par lequel les indicateurs de fonctionnalité peuvent être activés. Transmettez l’ID d’un indicateur de fonctionnalité au Feature.enable()
fonction:
$ Feature.enable(:certificate_based_clusters)
La modification s’applique immédiatement sans redémarrer GitLab. Cet exemple réactive la prise en charge des clusters Kubernetes basés sur des certificats dans GitLab 15.0.
Vous pouvez vérifier si un indicateur est activé avec un Feature.enabled?()
appel:
$ Feature.enabled?(:certificate_based_clusters) => true
Pour désactiver un indicateur de fonctionnalité, transmettez son ID au Feature.disable()
méthode:
$ Feature.disable(:certificate_based_clusters)
Tester la livraison des e-mails
La console vous permet d’envoyer directement des messages de test pour vérifier que votre système de messagerie sortant fonctionne :
$ Notify.test_email("example@example.com", "Test subject", "Test body").deliver_now
L’e-mail sera envoyé immédiatement en utilisant le même mécanisme que les messages créés par les fonctions de l’application GitLab.
Exécution de scripts Ruby avec Rails Runner
Une session de console interactive n’est pas toujours nécessaire. Le Rails Runner est une alternative qui facilite l’exécution de scripts Ruby dans le contexte de votre environnement GitLab.
Utilisez le gitlab-rails runner
commande pour exécuter du code Ruby. Votre script peut référencer les mêmes variables et objets GitLab qui sont disponibles pour une session de console Rails.
$ sudo gitlab-rails runner "puts User.find_by_username('demo').email"
Rails exécutera le script que vous fournissez, puis terminera le processus. L’exemple ci-dessus émet l’adresse e-mail de l’utilisateur GitLab appelé demo
. Cette alternative exécute le code Ruby fourni sous forme de fichier :
$ sudo gitlab-rails runner /scripts/gitlab-rails-script.rb
Les scripts enregistrés en tant que fichiers Ruby doivent être accessibles sous Unix git
utilisateur. GitLab Rails s’exécute toujours comme git:git
ainsi, les scripts appartenant à d’autres utilisateurs pourraient produire une erreur. Les chemins de fichiers non valides seront interprétés comme du code Ruby à exécuter, produisant une erreur de syntaxe qui peut masquer le véritable problème :
$ sudo gitlab-rails runner /scripts/invalid-file.rb Please specify a valid ruby command or the path of a script to run. Run 'rails runner -h' for help
Sommaire
La console GitLab Rails est un utilitaire puissant pour interagir directement avec votre instance GitLab. Il peut être un outil de débogage inestimable lorsque vous rencontrez des problèmes avec votre installation. La console vous permet également de créer des scripts de tâches d’administration à l’aide de code Ruby brut, au lieu de vous fier à l’API GitLab. Certaines opérations telles que l’activation de l’indicateur de fonctionnalité ne peuvent être réalisées qu’avec la console.
Avec le pouvoir vient la responsabilité. La console est capable d’ignorer les barrières de sécurité et d’accepter des opérations dans des contextes pour lesquels elles ne sont pas conçues. Une utilisation incorrecte peut entraîner une perte de données et un comportement inattendu. En utilisant la console, vous soulevez le couvercle sur la base de code de GitLab et ses opérations internes. Les méthodes disponibles et leurs effets manquent d’une garantie de support et peuvent changer sans avertissement.