Merge Methods, Merge Trains, Mergeability Checks, Conflict Resolution, and Integration Strategies: Concepts, Architecture, and Mental Model

1. Why the integration method is part of the delivery design

Chapter 08 answered whether a change is allowed to integrate. Chapter 09 asks what happens after authorization. Two teams can review the same source commit and still produce very different target histories: one records an explicit merge commit, another requires a linear fast-forward, and a third squashes ten review commits into one target commit. Those outcomes change rollback, bisecting, release provenance, and the SHA that downstream automation sees.

Integration therefore needs two models at once: Git history tells you which commits and parents exist, while GitLab merge-request state tells you which checks, discussions, pipelines, policies, and permissions permit the transition.

2. Merge methods are commit-graph policies

gitGraph
  commit id: "A"
  branch feature
  commit id: "B"
  commit id: "C"
  checkout main
  commit id: "D"
  branch merge_commit
  checkout merge_commit
  merge feature id: "M"
  checkout main

3. Mergeability is a state machine, not one boolean

A green-looking MR can still be unmergeable. GitLab evaluates multiple conditions asynchronously. Current REST responses expose detailed_merge_status; examples include conflict, draft_status, ci_must_pass, ci_still_running, discussions_not_resolved, not_approved, need_rebase, and mergeable.

Use detailed_merge_status instead of building automation around the older coarse merge_status. Because checking is asynchronous, an operator may need to poll after pushing or rebasing rather than assuming the first API response is final.

PROJECT_ID="123456"
MR_IID="17"

glab api "projects/$PROJECT_ID/merge_requests/$MR_IID"   --jq '{iid,state,draft,sha,source_branch,target_branch,has_conflicts,detailed_merge_status,head_pipeline}' 

4. Three pipeline questions that are easy to conflate

An ordinary merge-request pipeline runs against source-branch contents and is Free. It does not validate the source combined with the latest target. A merged results pipeline builds a temporary merged commit combining source and target and is Premium/Ultimate. A merge train orders multiple ready MRs and validates each in the context of earlier train entries, also Premium/Ultimate.

5. Conflict resolution changes code and often commit identity

A merge conflict is not a formatting inconvenience. Git is telling you that it cannot infer the intended combined state. The resolution must preserve the semantic intent of both sides or explicitly choose one. GitLab can resolve certain small UTF-8 text conflicts in the UI, but binary files, large files, path changes, or complex conflict sets require local Git.

The safe sequence is: capture source and target SHAs → fetch both refs → inspect the conflict → decide semantics → resolve → test → commit/rebase → push → re-check the MR. Do not click “use ours” or “use theirs” merely because it removes conflict markers.

6. Source-branch deletion is a lifecycle choice

Deleting a source branch after merge reduces clutter but also removes the easiest named pointer to the pre-merge source tip. The commits may remain reachable from the target or MR metadata, but recovery becomes less convenient. Capture the source SHA, merge/squash SHA, target SHA, and MR URL before deletion when those identities matter.

GitLab can default the “Delete source branch” option for new MRs. For fork-based MRs, the default comes from the fork. Deletion is performed by the merging/auto-merge actor and can fail if that actor lacks permission.

7. Inspect before changing merge behavior

Project settings and MR state are both readable through the API. The project response also reveals whether paid merged-results/train capabilities are enabled.

REPO="GROUP/integration-sandbox"
PROJECT_ID="123456"

glab auth status

glab api "projects/$PROJECT_ID"   --jq '{path_with_namespace,default_branch,merge_method,squash_option,only_allow_merge_if_pipeline_succeeds,only_allow_merge_if_all_discussions_are_resolved,remove_source_branch_after_merge,merge_pipelines_enabled,merge_trains_enabled}'

git fetch --all --prune
git log --graph --decorate --oneline --all -n 30

8. DevOps connection: integration policy defines evidence quality

Release automation often keys on a target SHA. Incident response may need to identify which reviewed source produced that SHA. A merge method that teams do not understand creates ambiguity exactly when traceability matters most. The policy should therefore state the intended graph, the pipeline evidence required for that graph, and which identities are recorded before cleanup.

Knowledge check

Summary

GitLab integration is a composition of Git graph policy, mergeability checks, CI evidence, conflict resolution, and branch lifecycle. Merge methods are Free; merged-results pipelines and merge trains are paid. Reliable operators preserve SHAs and prove the post-merge graph rather than assuming the UI label predicts every resulting commit.

Official references

• GitLab Docs — Merge methods
• GitLab Docs — Squash and merge
• GitLab Docs — Merge conflicts
• GitLab Docs — Merge trains
• GitLab Docs — Merged results pipelines
• GitLab Docs — Merge request pipelines
• GitLab Docs — Auto-merge
• GitLab Docs — Merge requests API
• GitLab Docs — Projects API
• GitLab Docs — Project settings
• GitLab Docs — Merge requests
• GitLab Docs — Default branch
• GitLab Docs — Merge trains API
• GitLab Docs — REST API pagination
• GitLab Docs — glab API