Configuration initiale de GitLab après l'installation

Juste après l’installation, GitLab est en état “ouvert” : n’importe qui peut créer un compte, les emails ne partent pas, et aucune sauvegarde n’est planifiée. Cette page couvre les réglages à faire en priorité avant de donner accès à votre équipe : SMTP, sécurité des comptes, SSH, et sauvegardes. Tous ces paramètres se configurent dans un seul fichier : /etc/gitlab/gitlab.rb.

Le fichier de configuration gitlab.rb

Tout GitLab self-managed se configure dans /etc/gitlab/gitlab.rb. C’est un fichier Ruby où chaque paramètre est une ligne de la forme cle['valeur'] = ....

# Ouvrir la configuration
sudo nano /etc/gitlab/gitlab.rb

# Appliquer les changements (obligatoire après chaque modification)
sudo gitlab-ctl reconfigure

reconfigure prend 2-5 minutes

gitlab-ctl reconfigure recrée tous les fichiers de configuration internes à GitLab. Ne coupez pas le processus en cours de route. Si vous avez plusieurs modifications à faire, groupez-les avant de lancer un seul reconfigure.

Le fichier /etc/gitlab/gitlab.rb fait ~3000 lignes en incluant tous les commentaires. La grande majorité des lignes est commentée — vous ne modifiez que ce dont vous avez besoin.

Configurer l’envoi d’emails (SMTP)

Sans SMTP, GitLab ne peut pas envoyer de notifications, d’invitations ou de liens de mot de passe oublié.

SMTP externe (Gmail, SendGrid…)

/etc/gitlab/gitlab.rb

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.gmail.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "votre-email@gmail.com"
gitlab_rails['smtp_password'] = "votre-mot-de-passe-app"
gitlab_rails['smtp_domain'] = "gmail.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_tls'] = false

# Adresse expéditeur des emails GitLab
gitlab_rails['gitlab_email_from'] = 'gitlab@votrdomaine.com'
gitlab_rails['gitlab_email_reply_to'] = 'noreply@votredomaine.com'

Gmail : utilisez un mot de passe d'application

Avec Gmail, n’utilisez jamais votre mot de passe principal. Créez un mot de passe d’application dans les paramètres de sécurité Gmail (nécessite la validation en deux étapes activée).

SMTP local (Postfix)

/etc/gitlab/gitlab.rb

# Utiliser le MTA local (Postfix doit être configuré)
gitlab_rails['smtp_enable'] = false
# GitLab utilise sendmail en fallback → Postfix local

Si Postfix est installé sur le serveur, GitLab l’utilise automatiquement. Vérifiez que Postfix fonctionne :

echo "Test" | mail -s "Test GitLab" votre@email.com

Pas d'email (lab/test)

Pour un lab sans besoin d’emails :

/etc/gitlab/gitlab.rb

gitlab_rails['smtp_enable'] = false

Les notifications seront désactivées — acceptable pour un lab.

Vérifier que les emails partent :

# Depuis le serveur, via la console Rails
sudo gitlab-rails console

# Puis dans la console Rails :
Notify.test_email('destinataire@test.com', 'Test GitLab', 'Contenu test').deliver_now

Résultat attendu (aucune erreur) :

Sent mail to destinataire@test.com (1234.5ms)

Tapez exit pour quitter la console.

Désactiver les inscriptions publiques

Par défaut, GitLab autorise n’importe qui à créer un compte. À désactiver en production.

Via l'interface web

1. Connectez-vous en tant qu’administrateur
2. Admin Area → Settings → General
3. Déroulez Sign-up restrictions
4. Décochez Sign-up enabled
5. Cliquez Save changes

Via gitlab.rb

/etc/gitlab/gitlab.rb

gitlab_rails['gitlab_signup_enabled'] = false

Puis appliquer :

sudo gitlab-ctl reconfigure

Liste blanche de domaines email

Si vous voulez autoriser uniquement votre domaine d’entreprise, utilisez Admin Area → Settings → General → Sign-up restrictions → Allowed domains for sign-ups.

Exemple : autoriser uniquement @monentreprise.com.

Configurer le port SSH GitLab

Par défaut, GitLab utilise le port 22 pour les clones SSH — le même que votre serveur SSH. Sur un serveur qui a également SSH pour l’administration, c’est un conflit.

Trois approches selon votre situation :

Approche	SSH admin	SSH Git	Quand utiliser
Port SSH distinct	22	2222	Serveur admin + GitLab sur même IP
URL SSH distincte	domaine:22	git.domaine:22	Reverse proxy / DNS séparé
Garder port 22	≠ port (ex: 2222)	22	GitLab est la fonction principale

Glissez pour voir

Pour utiliser un port SSH différent pour GitLab (ex: 2222) :

/etc/gitlab/gitlab.rb

gitlab_rails['gitlab_shell_ssh_port'] = 2222

Après gitlab-ctl reconfigure, les URLs de clone s’afficheront avec :2222.

Ce paramètre est cosmétique

gitlab_shell_ssh_port change uniquement l’URL affichée dans l’interface. Pour écouter réellement sur un autre port, modifiez aussi openssh-server ou le port 22 de votre SSH admin.

Configurer les sauvegardes automatiques

GitLab n’a pas de sauvegarde automatique par défaut. Configuration recommandée :

Paramètres de sauvegarde dans gitlab.rb

/etc/gitlab/gitlab.rb

# Dossier de destination des sauvegardes
gitlab_rails['backup_path'] = "/var/opt/gitlab/backups"

# Durée de conservation (en secondes) — ici 7 jours
gitlab_rails['backup_keep_time'] = 604800

# Exclure certains éléments lourds si besoin
# gitlab_rails['env'] = { "SKIP" => "builds,artifacts" }

Planifier les sauvegardes avec cron

# Éditer le crontab de root
sudo crontab -e

Ajouter une ligne pour une sauvegarde quotidienne à 2h du matin :

0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON=1 >> /var/log/gitlab-backup.log 2>&1

Le paramètre CRON=1 supprime les messages informatifs et ne garde que les erreurs dans les logs.

Lancer une sauvegarde manuelle

sudo gitlab-backup create

Résultat attendu :

2026-03-28 10:15:30 +0000 -- Dumping database ...
2026-03-28 10:15:45 +0000 -- Dumping database ... done
2026-03-28 10:15:45 +0000 -- Dumping repositories ...
...
2026-03-28 10:16:30 +0000 -- Creating backup archive: 1743157890_2026_03_28_18.10.1_gitlab_backup.tar ...
2026-03-28 10:16:35 +0000 -- Backup 1743157890_2026_03_28_18.10.1 is done.

Le fichier est créé dans /var/opt/gitlab/backups/.

Sauvegarder aussi les secrets

Le fichier de backup GitLab ne contient PAS les clés de chiffrement. Sauvegarder séparément (hors du serveur GitLab) :

• /etc/gitlab/gitlab.rb — configuration
• /etc/gitlab/gitlab-secrets.json — clés de chiffrement (CI variables, 2FA…)

Sans gitlab-secrets.json, une restauration ne déchiffrera pas les données.

Autres paramètres recommandés

Limiter la taille des dépôts et des transferts

/etc/gitlab/gitlab.rb

# Taille max d'importation de projet (Mo) — défaut illimité
gitlab_rails['max_attachment_size'] = 25

# Limite de profondeur du fetch initial (performances réseau)
# gitlab_rails['gitlab_default_projects_features_builds'] = true

Activer HTTPS (production)

Si vous avez un nom de domaine avec DNS public :

/etc/gitlab/gitlab.rb

# Let's Encrypt automatique
external_url 'https://gitlab.monentreprise.com'
letsencrypt['enable'] = true
letsencrypt['contact_emails'] = ['admin@monentreprise.com']

GitLab demande et renouvelle le certificat automatiquement.

Pour un certificat existant (ex: wildcard) :

external_url 'https://gitlab.monentreprise.com'
nginx['ssl_certificate'] = "/etc/ssl/certs/gitlab.crt"
nginx['ssl_certificate_key'] = "/etc/ssl/private/gitlab.key"

Désactiver Prometheus si ressources limitées

Prometheus consomme ~200-400 Mo de RAM. Sur un lab avec contraintes :

/etc/gitlab/gitlab.rb

prometheus_monitoring['enable'] = false

Cela désactive aussi Alertmanager, Node Exporter et les exporteurs associés.

Vérification complète

Après toutes vos modifications et un gitlab-ctl reconfigure, validez :

# Tous les services actifs
sudo gitlab-ctl status

# Diagnostic complet
sudo gitlab-rake gitlab:check SANITIZE=true

# Envoyer un email de test (remplacer l'adresse)
sudo gitlab-rails runner "Notify.test_email('test@example.com', 'Test', 'OK').deliver_now"

gitlab-rake vs gitlab-rails runner

• gitlab-rake gitlab:check — vérifie la santé de l’installation (filesystem, DB, shell…)
• gitlab-rails runner "..." — exécute du Ruby dans le contexte Rails de GitLab (pour des opérations ponctuelles)
• gitlab-rails console — ouvre une console Rails interactive

À retenir

• Tout se configure dans /etc/gitlab/gitlab.rb — modifiez, puis sudo gitlab-ctl reconfigure.
• SMTP est indispensable en production : sans lui, les notifications et les réinitialisations de mot de passe ne fonctionnent pas.
• Désactiver les inscriptions publiques dès que GitLab n’est pas accessible uniquement à votre équipe.
• Sauvegarder /etc/gitlab/gitlab-secrets.json hors du serveur — sans ce fichier, la restauration est impossible.
• Groupez vos modifications dans gitlab.rb avant de lancer un seul reconfigure pour économiser du temps.
• gitlab-ctl tail en parallèle lors d’un reconfigure aide à diagnostiquer les problèmes en temps réel.

Prochaines étapes

Sauvegarder et restaurer GitLab Stratégie de backup complète, restauration testée, stockage objet.

GitLab Runner Ajouter un runner pour exécuter vos pipelines CI/CD.

Mettre à jour GitLab Procédure de mise à jour mineure et majeure en sécurité.

Installation GitLab Revenir aux étapes d'installation et de prérequis.

×

📖 Voir la documentation →