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@votredomaine.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 ci-dessous ; la stratégie complète (stockage objet, restauration testée) est détaillée dans Sauvegarder et restaurer GitLab :

Paramètres de sauvegarde dans gitlab.rb

Deux réglages décident de l'essentiel : le dossier de destination des archives et leur durée de conservation, au-delà de laquelle gitlab-backup create supprime les plus anciennes. Gardez le dossier sur un disque distinct de celui des données, sinon une panne disque emporte l'instance et ses sauvegardes.

/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 17:39:09 UTC -- Dumping database ...
2026-03-28 17:39:10 UTC -- Dumping database ... done
2026-03-28 17:39:10 UTC -- Dumping repositories ...
...
2026-03-28 17:39:11 UTC -- Creating backup archive: 1774719549_2026_03_28_18.10.1_gitlab_backup.tar ... done
2026-03-28 17:39:11 UTC -- Backup 1774719549_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

Une instance qui démarre n'est pas encore une instance prête pour la production. Trois réglages de /etc/gitlab/gitlab.rb reviennent presque toujours : limiter la taille des transferts, servir l'interface en HTTPS, et couper la supervision intégrée quand la machine manque de mémoire. Les deux derniers ne prennent effet qu'après sudo gitlab-ctl reconfigure ; le premier se règle hors de gitlab.rb, comme l'explique son paragraphe.

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

Une pièce jointe déposée dans une issue ou une merge request est stockée sur le disque de l'instance. Plafonner sa taille évite qu'un fichier volumineux remplisse le volume des données. Ce plafond ne se règle pas dans gitlab.rb : c'est un réglage de l'application, stocké en base. Il se change dans l'interface, sous Admin > Settings > General > Account and limit, champ Maximum attachment size (MiB), ou par l'API application/settings. Le push maximal (Maximum push size) et la taille d'un dépôt (Size limit per repository, réservée aux éditions Premium et Ultimate) se règlent au même endroit, dans l'interface.

# Taille maximale d'une pièce jointe : 25 Mo (jeton d'un administrateur)
curl --request PUT --header "PRIVATE-TOKEN: <jeton-administrateur>" \
  "https://gitlab.monentreprise.com/api/v4/application/settings?max_attachment_size=25"

La réponse JSON contient "max_attachment_size": 25 quand le changement est pris en compte, sans reconfigure. Si vous fixez une valeur supérieure à celle du serveur web, les envois échouent en erreur 413 ; sur une installation par paquet Linux, on relève alors nginx['client_max_body_size'] dans /etc/gitlab/gitlab.rb.

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

Une fois ces vérifications au vert, l'instance est prête à recevoir ses premiers projets. Pour exécuter des pipelines, ajoutez un runner en suivant Maîtriser GitLab Runner. Chaque nouvelle version de GitLab est ensuite appliquée par la procédure de mise à jour, toujours précédée d'une sauvegarde et d'un nouveau gitlab-ctl status.

À 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.

×

📖 Voir la documentation →