Branches

Ce document décrit les règles appliquées automatiquement par le hook pre-receive côté serveur GitLab. Certaines sont bloquantes (push refusé), d'autres sont advisory (warning à l'écran, push accepté).

En résumé

Règle	Statut
Pas de push direct sur master / staging	Bloquant
Pas de force push sur master / staging	Bloquant
Pas de fast-forward sauf depuis source autorisée	Bloquant
Convention de nommage des branches (Conventional Branches)	Bloquant
Pas de réintroduction de staging dans une branche de travail	Bloquant
Convention de messages de commit (Conventional Commits)	Warning seulement
Bypass [HOTFIX] en cas d'urgence prod	Tracé

Pourquoi ces règles

master et staging alimentent les pipelines de déploiement. On veut que tout y arrive revu et tracé (via MR ou merge commit explicite), jamais par un push direct qui contournerait le review. Les conventions de nommage rendent les branches lisibles dans GitLab + nos dashboards CI.

Branches protégées - master et staging

Pas de push direct

Tu ne peux pas faire ça :

git checkout staging
git commit -m "fix"
git push origin staging

Le serveur refuse avec :

Non. Tes commits sur staging viennent ni de develop, ni de staging, ni d'une release/*. Soit tu FF depuis une branche source, soit tu fais un merge commit.

Comment faire à la place :

• Via l'UI GitLab => créer une Merge Request et la valider. C'est la voie royale, et le hook fait confiance au protocole web (le merge passe sans recheck d'historique).

• Via ton client git local (GitKraken, CLI, etc.) => merge commit explicite, sans fast-forward :

  git checkout staging
  git merge --no-ff develop
  git push origin staging

GitKraken et fast-forward

Dans GitKraken, décoche l'option "fast-forward" lors du merge. Le commit de tip doit avoir deux parents (un merge commit), sinon le hook le voit comme un push direct.

Sources de fast-forward autorisées

Le hook accepte un FF depuis une branche source connue (les commits doivent déjà exister dans la source) :

Cible	Sources acceptées en FF
master	staging, develop, release/*
staging	develop, release/*

Toute autre branche source en FF => refus.

Pas de force push

git push --force sur master ou staging est refusé. Le hook détecte les non-fast-forward (réécriture d'historique) et bloque.

Force push / non-FF detecte sur staging. Non.

Si tu penses avoir besoin de force push, viens en parler - on a quasi toujours une autre solution.

Création initiale autorisée

Quand master / staging n'existent pas encore (nouveau repo, migration), le premier push qui les crée passe sans contrôle. Les règles s'appliquent dès le second push.

Convention de nommage des branches (Conventional Branches)

Spec officielle : conventional-branch.github.io

Patterns acceptés par le hook :

Pattern	Usage
master	Production
staging	Recette / tests d'intégration
develop	Intégration continue
develop/<nom>	Variante develop par sous-équipe
feature/<nom>	Nouvelle fonctionnalité
fix/<nom>	Correction de bug courante
bugfix/<nom>	Synonyme de fix/ (alias accepté)
hotfix/<nom>	Correctif urgent à pousser en prod
release/<nom>	Préparation d'une release / hotfix path
chore/<nom>	Maintenance, deps, config, doc

Exemples valides :

feature/auth-sso
fix/null-pointer-checkout
hotfix/urgent-prod-crash
release/2026-q2
chore/bump-deps

Exemples refusés :

ma-branche
wip
test123
machin/truc

Nom de branche degueulasse. Respecte le format: develop, feature/., fix/., hotfix/.

Renommer une branche existante

git branch -m ancien-nom feature/nouveau-nom
git push origin -u feature/nouveau-nom
git push origin --delete ancien-nom

Convention des messages de commit (Conventional Commits)

Spec officielle : conventionalcommits.org/fr/v1.0.0

Optionnel mais encouragé

Le hook n'empêche pas un push si tes messages ne respectent pas le format. Il te liste juste les commits non conformes pour te faire un rappel à l'ordre amical.

Format attendu :

<type>(<scope>)?: <description>

[corps optionnel]

[footer optionnel]

Types reconnus :

Type	Pour quoi
feat	Nouvelle fonctionnalité
fix	Correction de bug
docs	Documentation seulement
style	Formatage, espaces, point-virgules (pas de logique)
refactor	Réécriture sans changer le comportement
perf	Amélioration de performance
test	Ajout / modification de tests
build	Build system, dépendances
ci	Config CI/CD
chore	Tâches de maintenance
revert	Revert d'un commit précédent

Exemples :

feat(auth): support du SSO via Azure AD
fix(checkout): null pointer quand le panier est vide
docs(cloud): ajouter la page SSH natif
chore(deps): bump newtonsoft.json à 13.0.3
feat!: supprime l'ancien endpoint /v1/users

Le ! après le type ou le scope indique un breaking change.

Si tes commits ne sont pas conformes, le hook affiche :

3 commit(s) ne respectent pas Conventional Commits :
   - a1b2c3d4  fix some stuff
   - e5f6g7h8  wip
   - i9j0k1l2  update
   Format attendu : <type>(scope)?: description
   (Push accepte cette fois, mais fais un effort la prochaine fois.)

Anti-pollution - pas de staging dans une branche de travail

Si tu fais git merge staging dans ta feature/* pour récupérer du code, ta branche contient maintenant tout l'historique de staging. Quand tu voudras la merger sur develop ou master, tu vas y rapporter du code "staging-only" qui n'a jamais été validé. Le hook bloque ça :

Tu fais quoi la ?

Comment éviter :

• Pour récupérer du code récent, rebase sur develop (pas sur staging)
• Si tu as besoin d'un fix qui est sur staging mais pas develop, c'est le signe que le fix doit aussi aller sur develop => fais une MR pour le porter

Bypass HOTFIX d'urgence

Si le dernier commit poussé contient [HOTFIX] dans son message, toutes les règles sont ignorées.

git commit -m "[HOTFIX] fix crash login prod"
git push origin master

HOTFIX detecte. Bon... pour cette fois ca passe. Abuse pas.

À utiliser uniquement quand prod brûle

Chaque utilisation est tracée dans /tmp/pre-receive.log côté serveur. C'est une convention sociale (n'importe qui peut taper [HOTFIX]), pas un contrôle technique => on regarde, et on demande des comptes si c'est utilisé pour du confort.

Flow recommandé

1. Branche depuis develop => git checkout -b feature/X develop
2. Commit sur ta feature, push, itère
3. Quand c'est prêt à tester => merge feature/X sur staging pour la recette
4. Recette OK => merge feature/X sur develop (pas staging vers develop !)
5. Merge develop sur master => le déploiement continu prend le relais

Toujours rapporter depuis la feature/*

Quand staging est OK, tu merges la feature sur develop, pas staging. Sinon tu rapporterais aussi tout le code des autres features qui cohabitent sur staging mais qui ne sont pas encore validées.

staging n'est pas une source de vérité

La vérité, c'est develop => master. staging est juste une zone de cohabitation pour tester plusieurs features en parallèle. Le hook bloque tout merge staging => develop ou staging => master justement pour t'éviter de polluer ces branches.

Erreurs fréquentes et solutions

Message du serveur	Ce qui s'est passé	Solution
Non. Tes commits sur staging viennent ni de develop...	Push direct ou FF depuis une source non autorisée	MR via UI, ou merge --no-ff depuis develop/release/*
Force push / non-FF detecte sur staging. Non.	git push --force sur master/staging	Pas de force push. Crée une autre branche.
Nom de branche degueulasse	Nom hors convention	git branch -m ancien feature/nouveau
Tu fais quoi la ?	staging mergé dans une feature/*	Rebase sur develop à la place
Creation initiale de master detectee	Premier push d'un nouveau repo	OK, c'est attendu
Merge via UI GitLab accepte	Merge depuis l'UI	OK, voie royale
X commit(s) ne respectent pas Conventional Commits	Messages non conformes	Warning seul, push accepté. Fais mieux la prochaine fois

Choses à éviter

• Ne commit pas directement sur master / staging en local - même sans push tout de suite, tu t'exposes à un refus côté serveur
• Ne fais pas de merge fast-forward depuis ton client sur master/staging - le hook ne voit pas ça comme un merge. Toujours --no-ff ou via UI
• N'utilise pas [HOTFIX] par confort - c'est loggé, c'est pour les vraies urgences prod
• Ne renomme pas master en main localement - hors convention, hook bloque
• Ne merge pas staging dans une feature - utilise develop comme base
• Ne push pas de gros binaires ou de secrets - pas bloqué par ce hook, mais surveillé par d'autres outils

Si tu es bloqué

1. Lis le message d'erreur, il est en français et il dit ce qui ne va pas
2. Regarde le tableau des erreurs ci-dessus
3. Logs côté serveur : docker exec gitlab tail -f /tmp/pre-receive.log
4. Si vraiment tu ne comprends pas, ping l'équipe DevOps

Le hook est là pour protéger le code partagé, pas pour t'embêter. Si une règle te semble absurde dans un cas précis, viens en parler - on peut l'adapter.

Contributors

Clément Favre

Changelog

Last edited about 2 months ago

View full history

b07d2bb-docs: add Crans-Montana headless and police intranets to parc inventory