Pourquoi GitLab CE plutôt que GitHub ou Bitbucket
GitHub et Bitbucket sont des services gérés : pratiques au démarrage, mais leur modèle tarifaire évolue avec la taille de l'équipe, les minutes CI sont comptées sur les offres gratuites, et votre code est hébergé sur une infrastructure tierce. GitLab CE renverse cette équation : vous déployez la forge sur votre VPS, vous gardez la maîtrise totale du code et des données, et la CI/CD est incluse sans quota de minutes imposé par un tiers — seule la capacité de votre machine limite le nombre de jobs parallèles. Pour une agence ou une équipe de développeurs qui facture au client ou traite des données sensibles, ce contrôle est souvent non négociable. GitLab CE est aujourd'hui l'une des forges git les plus déployées en self-hosted : sa base de code est publique, son noyau est libre, et ses dix ans d'existence lui ont valu une communauté de contributeurs qui maintient l'outil actif entre deux releases Enterprise.
Ce que GitLab CE inclut d'emblée
- Forge git complète : dépôts privés et publics, merge requests, code review, protection de branches et CODEOWNERS.
- CI/CD intégrée sans limite de minutes imposée : pipelines YAML (
.gitlab-ci.yml), environments, deploy tokens et artifacts. - Registry Docker privé hébergé sur votre domaine :
docker pull git.votredomaine.com/groupe/image:tagsans compte Docker Hub. - Wikis et pages par projet et par groupe, avec rendu Markdown complet.
- Gestion d'issues et milestones : tableau kanban, labels, itérations et burndown chart inclus.
- Runners parallèles : enregistrez autant de runners que vous voulez sur votre infra ou vos CI workers.
- Webhooks pour notifier un outil tiers (Slack, PagerDuty, votre serveur de déploiement) à chaque push ou merge.
- RBAC granulaire avec cinq niveaux d'accès (Guest, Reporter, Developer, Maintainer, Owner) et support LDAP/SAML optionnel.
Prérequis : ce qu'il faut avant de commencer
GitLab CE est gourmand en mémoire — c'est l'un de ses inconvénients les plus cités par rapport à Forgejo ou Gitea. Prévoyez 4 Go de RAM minimum pour un usage léger (moins de dix utilisateurs actifs) ; 8 Go sont recommandés dès que vous ajoutez des runners sur la même machine ou que vous activez le registry Docker. En dessous de 4 Go, Puma et Sidekiq se disputent la mémoire et GitLab répond en 502 sous charge. Côté disque, comptez au moins 20 Go pour l'installation et les dépôts initiaux — prévoir 50 Go si vous comptez stocker des images Docker dans le registry. Vous avez également besoin : d'un nom de domaine pointant vers l'IP du VPS (par exemple git.votredomaine.com) pour que Let's Encrypt puisse émettre le certificat TLS ; des ports 80, 443 et 22 ouverts dans votre pare-feu (le port 22 est utilisé par GitLab pour les push SSH — si votre daemon SSH système écoute aussi sur 22, vous devrez le déplacer sur un autre port) ; de Docker Engine et du plugin Compose v2 installés (docker compose version doit répondre v2.x).
De l'installation à votre premier projet
Créer l'arborescence de dossiers
Créez un dossier dédié et les trois volumes persistants que GitLab utilise : mkdir -p /opt/gitlab/{config,logs,data}. Ces dossiers seront montés dans le conteneur ; sans eux, la configuration et les dépôts disparaissent à chaque docker compose down.
Écrire le fichier docker-compose.yml
Créez /opt/gitlab/docker-compose.yml. La clé GITLAB_OMNIBUS_CONFIG concentre toute la configuration spécifique à votre instance — remplacez git.votredomaine.com par votre domaine réel. Définissez le service gitlab avec l'image gitlab/gitlab-ce:17.2.1-ce.0, restart: unless-stopped, le hostname, les variables d'environnement (dont GITLAB_OMNIBUS_CONFIG contenant external_url, la configuration Let's Encrypt et les paramètres SMTP), les ports 80, 443 et 22, les volumes /opt/gitlab/config:/etc/gitlab, /opt/gitlab/logs:/var/log/gitlab et /opt/gitlab/data:/var/opt/gitlab, shm_size: 256m et env_file: .env. Note importante : la valeur de external_url détermine si GitLab génère des URLs en http:// ou en https://, et si Let's Encrypt est tenté. Elle doit correspondre exactement au nom de domaine résolvable depuis Internet — une valeur incorrecte est la première cause d'erreur d'accès.
Renseigner GITLAB_OMNIBUS_CONFIG
Dans GITLAB_OMNIBUS_CONFIG, définissez au minimum : external_url 'https://git.votredomaine.com' ; letsencrypt['enable'] = true avec letsencrypt['contact_emails'] = ['[email protected]'] ; les paramètres SMTP — gitlab_rails['smtp_enable'] = true, gitlab_rails['smtp_address'], gitlab_rails['smtp_port'] = 587, gitlab_rails['smtp_user_name'], gitlab_rails['smtp_password'] = ENV['GITLAB_SMTP_PASSWORD'], gitlab_rails['smtp_authentication'] = 'login', gitlab_rails['smtp_enable_starttls_auto'] = true, gitlab_rails['gitlab_email_from'] ; et si vous activez le registry : registry_external_url 'https://registry.votredomaine.com'. Toutes ces lignes doivent être dans le bloc GITLAB_OMNIBUS_CONFIG et non définies comme variables d'environnement séparées — une clé hors du bloc est silencieusement ignorée.
Créer le fichier .env pour les secrets
Créez /opt/gitlab/.env et restreignez ses permissions : touch /opt/gitlab/.env && chmod 600 /opt/gitlab/.env. Ajoutez-y vos variables sensibles — au minimum GITLAB_SMTP_PASSWORD=votre_mot_de_passe_smtp. Ne mettez jamais de mot de passe en clair dans le fichier Compose : il sera versionné ou partagé. Ajoutez .env à votre .gitignore si vous versionnez la configuration.
Démarrer GitLab et attendre l'initialisation
Lancez la stack : docker compose -f /opt/gitlab/docker-compose.yml up -d. Le premier démarrage est long : GitLab initialise la base de données, compile les assets et configure Nginx et Puma. Attendez environ 5 minutes avant d'accéder à l'interface web. Suivez l'avancement avec docker compose -f /opt/gitlab/docker-compose.yml logs -f gitlab et attendez le message gitlab Reconfigured!.
Récupérer le mot de passe root initial
À la première initialisation, GitLab génère un mot de passe temporaire pour le compte root. Récupérez-le avec : docker exec -it gitlab-gitlab-1 grep 'Password:' /etc/gitlab/initial_root_password. Ce fichier est supprimé automatiquement 24 heures après le premier démarrage — notez le mot de passe immédiatement.
Se connecter, changer le mot de passe et désactiver l'inscription ouverte
Ouvrez https://git.votredomaine.com dans votre navigateur. Connectez-vous avec root et le mot de passe récupéré. Rendez-vous dans User Settings → Password et définissez un nouveau mot de passe fort. Créez ensuite votre premier utilisateur non-root : Admin Area → Users → New User. Si GitLab est à usage interne, désactivez l'inscription publique : Admin Area → Settings → General → Sign-up restrictions → décochez « Sign-up enabled ».
Enregistrer un GitLab Runner
Les pipelines CI/CD nécessitent au moins un runner. Installez gitlab-runner sur le VPS ou une machine dédiée (binaire téléchargeable depuis la page officielle GitLab Runner). Récupérez le token d'enregistrement dans Admin Area → Runners (runner partagé) ou dans Settings → CI/CD → Runners de votre projet. Enregistrez le runner avec : gitlab-runner register --url https://git.votredomaine.com --registration-token VOTRE_TOKEN --executor docker --docker-image alpine:latest. Une fois enregistré, le runner apparaît en vert dans l'interface et vos pipelines .gitlab-ci.yml peuvent s'exécuter.
Vérifier l'envoi d'emails
Testez la configuration SMTP depuis la console Rails de GitLab : docker exec -it gitlab-gitlab-1 gitlab-rails console puis tapez Notify.test_email('[email protected]', 'Test GitLab', 'Bonjour').deliver_now. Si le mail n'arrive pas, vérifiez que les clés smtp_* sont bien à l'intérieur de GITLAB_OMNIBUS_CONFIG et consultez les logs : docker exec -it gitlab-gitlab-1 tail -f /var/log/gitlab/gitlab-rails/production.log.
Sauvegardes automatiques. GitLab embarque une commande de sauvegarde complète (dépôts, base de données, uploads) : docker exec -t gitlab-gitlab-1 gitlab-backup create. Planifiez-la dans crontab -e avec la ligne 0 3 * * * docker exec -t gitlab-gitlab-1 gitlab-backup create CRON=1. Les archives sont créées dans /var/opt/gitlab/backups (monté dans /opt/gitlab/data/backups sur l'hôte) et versionnées par timestamp. Synchronisez ce dossier vers un stockage externe (S3, rclone) — une sauvegarde locale n'est pas une sauvegarde.
Dépannage : les trois pannes les plus fréquentes
502 Bad Gateway au démarrage. GitLab met environ 5 minutes à être pleinement opérationnel. Si le 502 persiste, vérifiez que Puma a démarré : docker exec gitlab-gitlab-1 gitlab-ctl status puma. Un manque de RAM est la cause la plus fréquente — assurez-vous d'avoir au moins 4 Go disponibles. SMTP ne fonctionne pas. La première chose à vérifier : le bloc gitlab_rails['smtp_*'] est-il bien à l'intérieur de GITLAB_OMNIBUS_CONFIG, et non défini comme variable d'environnement séparée ? Une indentation incorrecte dans le YAML ou une clé hors du bloc omnibus est silencieuse — GitLab démarre normalement mais ignore la configuration SMTP. Testez depuis la console Rails (étape 9). Runner non connecté. Si le runner s'affiche en gris ou « offline », vérifiez qu'il peut joindre votre instance : gitlab-runner verify --url https://git.votredomaine.com. Un certificat TLS auto-signé ou un DNS non résolvable depuis la machine du runner sont les causes habituelles. Vérifiez également que le token utilisé à l'enregistrement est celui du bon niveau (instance, groupe ou projet).
GitLab CE, Forgejo ou Gitea : comment choisir
| Critère | GitLab CE | Forgejo / Gitea |
|---|---|---|
| Licence | MIT / EE Core | MIT |
| RAM au repos | 300–600 Mo (Puma + Sidekiq) | 30–50 Mo |
| CI/CD native | Oui (`.gitlab-ci.yml`, runners) | Forgejo : oui via Woodpecker CI ; Gitea : non native |
| Registry Docker intégré | Oui | Forgejo : oui ; Gitea : non natif |
| Wikis par projet | Oui | Oui |
| LDAP / SAML | Oui (CE) | Forgejo : oui ; Gitea : LDAP oui, SAML non |
| Courbe d'apprentissage | Élevée (interface riche) | Faible à moyenne |
| Idéal pour | Équipes 5+ avec CI, registry et RBAC | Équipes légères, forge simple, faible empreinte RAM |
Quand choisir GitLab CE, quand choisir Forgejo
GitLab CE est le bon choix si votre équipe a besoin d'une CI/CD robuste directement intégrée à la forge, d'un registry Docker privé sur votre domaine, de pipelines de déploiement avec environments et deploy tokens, ou d'une gestion de projet avec issues, milestones et kanban sans outil tiers. Son empreinte mémoire (4–8 Go) est le prix de cette richesse fonctionnelle. Forgejo ou Gitea s'imposent quand la mémoire est la contrainte principale, quand la forge est l'unique besoin (pas de CI intégrée) et que vous pilotez la CI avec un outil externe (Woodpecker, Drone, GitHub Actions via un runner). Sur un VPS de 2 Go, GitLab CE n'est pas viable ; Forgejo tourne sur 256 Mo. Sur un VPS de 8 Go dédié à une équipe de développeurs, GitLab CE offre un environnement complet que GitHub met sur sa plateforme SaaS — sous votre contrôle et sans abonnement mensuel par utilisateur.
