GitLab delete project : comment supprimer un projet GitLab sans erreur

La requête gitlab delete project revient souvent quand une équipe veut faire du ménage, fermer un POC, retirer un dépôt obsolète ou nettoyer un namespace avant migration. En pratique, supprimer un projet GitLab n’est pas une simple formalité d’interface. Il faut vérifier les droits, protéger les variables CI/CD, garder une copie du dépôt et éviter de casser une chaîne de livraison encore active. Si tu interviens sur une instance GitLab d’entreprise, la bonne approche consiste à traiter cette action comme un mini change : qualification, sauvegarde, suppression, puis contrôle. C’est cette méthode terrain que je détaille ici.

Réponse rapide

Pour réussir un gitlab delete project sans incident, il faut suivre 6 étapes : identifier le vrai propriétaire du projet, vérifier qu’aucun pipeline ni runner critique n’en dépend, exporter ou cloner le dépôt, archiver si un doute subsiste, lancer la suppression avec un compte Owner, puis contrôler la période de restauration ou la suppression définitive selon l’édition GitLab utilisée.

Pourquoi la suppression GitLab mérite une procédure

En PME comme en startup, un projet GitLab concentre plus que du code source : variables CI/CD, wiki, snippets, artefacts, historique des merge requests, dépendances de runners, webhooks et parfois même des secrets oubliés. Une suppression précipitée peut donc casser plusieurs couches d’exploitation d’un seul coup. C’est particulièrement vrai quand GitLab sert de point d’entrée commun entre dev et ops.

On voit souvent trois cas métier : un projet POC devenu inutile, un dépôt remplacé par un mono-repo, ou un projet dupliqué qui parasite la lisibilité du namespace. Dans les trois cas, le réflexe sain n’est pas “supprimer tout de suite”, mais “confirmer l’intention et prévoir le retour arrière”. Ce raisonnement rejoint la logique de gouvernance que j’évoquais déjà dans l’audit GitLab orienté secrets : avant une action risquée, on réduit l’incertitude.

Autre point important : sur une instance auto-hébergée, la politique de rétention peut être différente de GitLab.com. Le délai de suppression finale, l’usage de l’API ou les permissions disponibles varient selon la configuration de l’instance. Il faut donc rester prudent avec les tutos trop génériques.

Diagnostic avant suppression

Avant d’appuyer sur Delete, pose-toi les bonnes questions. Le projet a-t-il encore des pipelines planifiés ? Est-il référencé dans des playbooks Ansible, des runners, des scripts Terraform ou un portail interne ? Le namespace contient-il des forks ou des miroirs dépendants ? Une simple revue de la page projet et des paramètres CI/CD évite beaucoup d’ennuis.

Je recommande aussi de distinguer quatre statuts opérationnels :

Si le projet héberge un runner, pense à consulter aussi ce guide sur le déploiement d’un GitLab Runner avec Ansible. C’est un bon rappel des dépendances CI qu’on oublie trop facilement.

Causes fréquentes des erreurs

Les suppressions ratées viennent rarement d’un bug GitLab. Elles viennent surtout d’un processus incomplet :

• le décideur n’a pas le rôle Owner et contourne le sujet sans vraie validation ;
• l’équipe ne sait pas si le projet est encore référencé dans une automatisation ;
• aucune archive locale n’a été prise ;
• la différence entre archive, pending deletion et suppression définitive n’est pas comprise ;
• les variables CI/CD ou webhooks n’ont pas été inventoriés.

Ce point est encore plus sensible dans les environnements où GitLab porte à la fois le code, les runners et des scripts d’exploitation. Un simple projet “inutile” peut en réalité contenir un job de sauvegarde, une image de build ou un token historique.

Méthode pas à pas pour supprimer un projet GitLab proprement

Voici une séquence fiable, adaptée à un contexte pro. L’idée n’est pas de faire “plus de paperasse”, mais d’éliminer les erreurs bêtes.

1. Identifier le projet exact et son propriétaire

Commence par relever l’URL, le namespace, le project ID et le propriétaire opérationnel. Vérifie aussi si le projet appartient à un groupe avec politique de suppression restreinte.

2. Vérifier les dépendances avant action

Inspecte les pipelines, les schedules, les runners associés, les variables, les webhooks, les intégrations et le registre de conteneurs. Si le projet publie encore une image ou un artefact, note la destination de remplacement.

3. Prendre une copie exploitable

Au minimum, clone miroir + export du projet si disponible. Le clone miroir protège vite le dépôt Git ; l’export projet ajoute les éléments GitLab utiles au rollback.

git clone --mirror git@gitlab.example.com:groupe/projet.git
cd projet.git
git bundle create ../projet-backup.bundle --all

Si tu utilises l’API GitLab pour inventorier le projet avant suppression, garde le project_id et vérifie l’état des jobs récents :

curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN"   "https://gitlab.example.com/api/v4/projects/123456/pipelines?per_page=5"

4. Archiver quand le doute est non nul

Si l’objectif est surtout de retirer le bruit visuel, l’archivage reste souvent la meilleure première étape. Il coupe l’activité normale sans détruire l’historique. C’est une excellente option pour les dépôts de migration, les anciens projets clients ou les projets “en sommeil”.

5. Lancer la suppression avec un compte Owner

D’après la documentation GitLab, le rôle Owner est requis et la première suppression place généralement le projet en attente de suppression. Sur GitLab.com, la suppression finale intervient ensuite après la période de rétention définie par la plateforme. Sur self-managed, ce délai peut être ajusté par l’instance.

En interface, le chemin standard est :

Project overview → Actions → Delete
Confirmer le nom du projet
Valider la suppression

Si ton instance expose l’action API adaptée, tu peux aussi industrialiser le contrôle pour des opérations de lot, mais je déconseille l’automatisation en masse sans inventaire préalable.

6. Contrôler la fenêtre de restauration

Une fois le projet en pending deletion, vérifie qu’il apparaît bien comme inactif et qu’une action de restauration existe encore. Ce contrôle simple évite de découvrir trop tard qu’une politique locale supprime plus vite que prévu.

Prévention et garde-fous

Le plus efficace reste d’empêcher les suppressions improvisées. Une convention simple fonctionne très bien : chaque suppression passe par un ticket, avec propriétaire, date, backup, dépendances vérifiées et stratégie de retour arrière. Sur une petite équipe, ce ticket peut être très léger. L’important est d’avoir une trace.

Je conseille aussi :

• un tag ou topic GitLab pour les projets critiques ;
• une convention d’archivage avant suppression pour les dépôts inactifs ;
• un inventaire mensuel des projets orphelins ;
• un contrôle des variables et secrets avant export ou suppression.

Cette discipline évite que le ménage technique devienne une source d’incident. Elle aide aussi à garder un namespace GitLab plus lisible pour les équipes.

Checklist avant de lancer le bouton Delete

Erreurs courantes à éviter

FAQ

Conclusion

Le besoin gitlab delete project semble basique, pourtant il touche à la gouvernance, à la sécurité et à la continuité de service. En entreprise, la bonne méthode n’est pas de supprimer vite : c’est de supprimer proprement. Si tu confirmes le rôle Owner, cartographies les dépendances, prends un backup exploitable et utilises la fenêtre de restauration à ton avantage, tu transformes une action risquée en opération maîtrisée.