Merge Request (MR): cosa è, come crearlo e il processo di revisione

Cos'è un Merge Request (MR)?

Merge Request (MR) — una richiesta di integrare modifiche da un ramo Git a un altro, che avvia il processo di revisione del codice e controlli automatizzati. A differenza dell'unione diretta tramite console, l'MR crea una procedura formale: lo sviluppatore descrive le modifiche, assegna i revisori, avvia CI/CD e riceve feedback prima dell'applicazione delle modifiche. Questo è un elemento chiave di GitLab, ma il meccanismo equivalente in GitHub si chiama Pull Request (PR).

Secondo GitLab Documentation, 2026, più di 80 milioni di Merge Requests vengono creati in GitLab ogni anno. Ogni MR contiene quattro componenti principali: una descrizione con il contesto delle modifiche, un elenco di commit, la differenza di codice (diff) e la discussione (thread di discussione). Senza uno di questi elementi, l'MR è considerato incompleto.

Merge Request (MR) risolve tre compiti: impedisce modifiche dirette ai rami protetti (main, develop), fornisce controllo qualità attraverso la revisione e preserva la cronologia delle discussioni per futuri sviluppatori. In GitLab, lo stato dell'MR viene visualizzato nell'interfaccia con indicatori di colore: grigio per Draft, arancione per in attesa, verde per Approved, viola per Merged e rosso per Closed.

Terminologia: MR, PR e CR

Su diverse piattaforme Git, Merge Request viene chiamato in modo diverso. GitLab usa “Merge Request” (MR), GitHub usa “Pull Request” (PR). L'analogia è Change Request (CR) in Gerrit. Tutti e tre indicano lo stesso processo: una richiesta di integrare modifiche attraverso la revisione del codice. La scelta del termine dipende solo dalla piattaforma utilizzata nel progetto.

# Creare un ramo con modifiche
git checkout -b feature/add-auth
git commit -m "Add OAuth2 authentication flow"
git push origin feature/add-auth

# Puoi creare un MR tramite l'interfaccia GitLab/GitHub o la CLI:
gh pr create --title "Add OAuth2 authentication flow" \
  --body "Implements OAuth2 with Google and Apple providers" \
  --reviewer "team-lead"

MR vs PR: la differenza tra GitLab e GitHub

Merge Request in GitLab e Pull Request in GitHub sono meccanismi funzionalmente identici con nomi diversi. La differenza è dovuta alla storia: GitLab si è originariamente posizionato come alternativa self-hosted a GitHub e ha scelto il termine “merge request” per il processo di unione. GitHub, lanciato prima, ha usato “pull request” — una richiesta di “tirare” (pull) le modifiche nel ramo principale.

Secondo GitHub Docs, 2024, entrambi gli strumenti supportano lo stesso insieme di funzionalità: descrizione Markdown, assegnazione revisori, commenti su linee di codice specifiche, stati di controllo e unione automatica quando le condizioni sono soddisfatte. Le differenze riguardano l'interfaccia e le capacità aggiuntive.

Come creare un Merge Request: guida passo passo

La creazione di un Merge Request (MR) inizia con la pubblicazione di un ramo con modifiche nel repository remoto. Dopo il push verso GitLab o GitHub, l'interfaccia mostra un pulsante “Create Merge Request” o “Compare & Pull Request”. Lo sviluppatore compila la descrizione, specifica il ramo di destinazione (di solito develop o main), assegna i revisori e allega etichette.

Secondo GitLab Documentation, 2025, un MR standard contiene un titolo fino a 72 caratteri, una descrizione con template e un link all'issue. La descrizione dovrebbe rispondere alle domande: cosa è stato fatto, perché, come è stato testato. GitLab supporta la chiusura automatica degli issue all'unione tramite le parole chiave Closes, Fixes, Resolves.

# Esempio di template .gitlab/merge_request_templates/default.md
## What does this MR do?

[Breve descrizione delle modifiche: cosa e perché]

## How to test

1. Eseguire ./gradlew test
2. Verificare LoginActivity con il token di test
3. Assicurarsi che non ci sia regressione in AuthManager

## Related issues

Closes #142

Ciclo di vita dell'MR: da Draft a Merged

Merge Request (MR) attraversa cinque stati in GitLab. Il primo è Draft (bozza), contrassegnato dal prefisso “Draft:” nel titolo, che blocca l'unione. Quando è pronto, lo sviluppatore rimuove Draft e l'MR passa allo stato Opened — inizia la revisione del codice e si avvia la pipeline CI/CD.

Secondo GitLab Docs, 2024, nello stato Opened, i revisori esaminano il diff, lasciano commenti e richiedono modifiche tramite Resolve Threads. Quando tutti i thread sono risolti e CI/CD passa con successo, lo sviluppatore responsabile imposta Approve. Successivamente, l'MR può essere unito usando il pulsante Merge, o si può attendere l'unione automatica (Auto-merge).

GitLab supporta tre opzioni di stato finale: Merged (unito con successo), Closed (chiuso senza unione, ad esempio quando si abbandona una funzionalità) e Reopened (riapertura dopo la chiusura). Ogni stato viene registrato nella cronologia delle attività dell'MR per audit.

Stati automatici e trigger

GitLab aggiorna automaticamente lo stato del Merge Request al verificarsi di eventi: il push di nuovi commit reimposta le Approvals, al successo della pipeline CI lo stato diventa Pipeline passed, al fallimento — Pipeline failed (l'unione viene bloccata). Auto-merge può essere configurato: l'MR viene automaticamente unito dopo CI riuscito e ricevuta di tutte le approvazioni richieste.

• Draft — bozza, CI viene eseguito ma unione bloccata
• Opened — pronto per la revisione, revisori assegnati, pipeline attiva
• Approved — numero richiesto di approvazioni ricevuto
• Merged — modifiche unite nel ramo di destinazione
• Closed — chiuso senza unione

Regole di revisione del codice in Merge Request

La revisione del codice in Merge Request (MR) è una fase obbligatoria nella maggior parte dei progetti commerciali. Secondo la ricerca di SmartBear, 2023, la revisione del codice con MR riduce il numero di difetti del 30–60% e accelera l'inserimento di nuovi sviluppatori. La regola principale è che ogni MR sia controllato da almeno uno, preferibilmente due sviluppatori che non hanno partecipato alla scrittura del codice.

La verifica dell'MR include cinque criteri: correttezza logica, conformità allo stile del codice, copertura dei test, sicurezza e prestazioni. In GitLab è possibile configurare Required Approvals — il numero obbligatorio di approvazioni prima dell'unione, ad esempio 2 approvazioni per main e 1 per develop.

La discussione nell'MR viene condotta in Thread — commenti su linee di codice specifiche. Ogni thread deve essere risolto prima dell'unione. Per accelerare le revisioni, si consiglia di limitare la dimensione dell'MR: 200–400 righe di modifiche. Secondo Google Research (2022), gli MR con più di 400 righe vengono revisionati con un'efficacia inferiore del 30%.

Pipeline CI/CD in Merge Request

Alla creazione di un Merge Request (MR), la pipeline CI/CD viene avviata automaticamente. In GitLab ciò avviene attraverso il file .gitlab-ci.yml, in GitHub attraverso il workflow di GitHub Actions. La pipeline include build del progetto, test unitari, linter, analisi statica (SAST) e verifica della copertura del codice.

Secondo GitLab Blog, 2024, lo stato della pipeline viene visualizzato direttamente nell'MR: segno di spunta verde (passed), croce rossa (failed) o cerchio giallo (running). Se la pipeline fallisce, GitLab blocca il pulsante Merge fino alla correzione. Nelle impostazioni, è possibile abilitare “Merge when pipeline succeeds” — unione automatica dopo una pipeline riuscita.

# .gitlab-ci.yml — esempio per un progetto Android
test:
  stage: test
  script:
    - ./gradlew ktlintCheck
    - ./gradlew testDebugUnitTest
  only:
    - merge_requests

build:
  stage: build
  script:
    - ./gradlew assembleDebug
  only:
    - merge_requests

Metodi di unione: Squash, Merge Commit, Fast-Forward

GitLab e GitHub offrono tre metodi di unione per Merge Request. La scelta dipende dalla politica del team e dalla pulizia desiderata della cronologia. Merge Commit crea un commit di unione separato, preservando l'intera cronologia del ramo di funzionalità. Squash combina tutti i commit del ramo in un unico commit sul ramo di destinazione. Fast-Forward applica i commit linearmente senza un commit di unione.

Secondo GitLab Docs, 2025, Squash è preferibile per progetti con alta densità di commit (20+ commit in un ramo di funzionalità). Fast-Forward è obbligatorio per Trunk-Based Development. Merge Commit viene utilizzato in Git Flow per preservare la semantica di ramificazione.

• Merge Commit — preserva la cronologia, crea un commit di unione, adatto per Git Flow
• Squash — combina tutti i commit in uno, cronologia pulita, perde i commit intermedi
• Fast-Forward — cronologia lineare senza commit di unione, obbligatorio in TBD

Best practice: come scrivere un buon MR

Un Merge Request (MR) di qualità riduce i tempi di revisione e il numero di errori. La prima regola è che un MR risolve un compito. Se le modifiche riguardano più funzionalità non correlate, devono essere suddivise in MR separati. In secondo luogo, il titolo dell'MR dovrebbe essere informativo: “Add OAuth2 authentication with Google provider” invece di “Fix stuff” o “Update code”.

Secondo Google Engineering Practices, 2024, un buon MR contiene una descrizione del contesto: perché le modifiche sono necessarie, come sono state testate e quali rischi esistono. La dimensione dell'MR non deve superare le 400 righe di modifiche. Se il volume è maggiore, il compito deve essere scomposto in sotto-attività. Per documentazione e test, le eccezioni sono accettabili ma con spiegazione.

Merge Request (MR) dovrebbe includere test automatizzati per la nuova funzionalità. In GitLab è possibile configurare la politica Coverage Check — l'MR viene automaticamente bloccato se la copertura del codice scende al di sotto di una soglia (ad esempio 80%). Ciò garantisce che la nuova funzionalità non riduca la qualità complessiva del progetto.

• Un MR — un compito: scomporre le modifiche grandi in più MR piccoli
• Descrizione con template: utilizzare .gitlab/merge_request_templates per uniformità
• Dimensione fino a 400 righe: gli MR grandi vengono revisionati più lentamente e con più errori
• Test obbligatori: le nuove funzionalità devono essere coperte da test unitari

Template di descrizione MR

GitLab supporta i template di Merge Request attraverso i file .gitlab/merge_request_templates/. Il template include sezioni: cosa è stato fatto, come testare, attività correlate e checklist. L'uso dei template accelera la creazione di MR e garantisce che gli sviluppatori non dimentichino di includere informazioni importanti. Nella descrizione dell'MR, devono essere specificati gli issue correlati (Closes #N) per la chiusura automatica delle attività all'unione.