Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 36 ยท Administration and Best Practices

Branching and Workflow Best Practices

Choose a branching workflow for GitLab: feature branches, trunk-based development and GitLab Flow, merge methods, squash, merge trains, small merge requests and review habits.

Tools do not decide how a team works; habits do. A branching workflow is an agreement on where changes are made, how they are reviewed, and how they reach production. GitLab supports several, and the right choice depends on how you release: a website deployed ten times a day is not a mobile app released every month, and a library with several supported versions is a third case.

This lesson compares the common workflows, explains merge methods and merge trains, and lists habits that keep merge requests small and reviews useful. GitLab is not available on this site, so the settings are described by name and the examples are JavaScript models of branch rules and queues. If you want the Git fundamentals under all this, see the Git tutorial at /git.

Three common workflows

Trunk-based development. Everyone merges small changes into main several times a day. Branches live for hours, not weeks. Unfinished work stays hidden behind feature flags. This fits continuous delivery and needs strong automated tests, since main must always be releasable.

Feature branch workflow. Each change gets a branch and a merge request; after review and a green pipeline it merges into main. It is the default in most teams and works with both continuous and periodic releases.

GitLab Flow. Feature branches merge into main, and then changes flow downstream through environment or release branches:

  • Environment branches: main to staging to production. A merge into production means "deploy". Good when you must control when each environment changes.
  • Release branches: main to release/2.4, release/2.3. Bug fixes land in main first and are cherry-picked to the supported releases ("upstream first"). Good for software with several supported versions.
flowchart LR
  F["feature branch"] -->|"merge request"| M["main"]
  M -->|"deploy"| ST["staging environment"]
  M -->|"cherry-pick fix"| R24["release/2.4"]
  M -->|"cherry-pick fix"| R23["release/2.3"]
  ST -->|"approved"| PR["production"]

GitLab Flow: changes enter main first and then flow outward.

Avoid long-lived branches that diverge from main; the longer a branch lives, the more painful the merge, and the later you discover that the pieces do not fit.

Merge methods

In Settings > Merge requests you choose how a merge request joins the target branch:

Method History Notes
Merge commit A merge commit joins two lines Keeps every commit; the graph gets branchy
Merge commit with semi-linear history Requires a fast-forward possible; creates a merge commit Branch must be rebased first
Fast-forward merge No merge commit; strictly linear Needs rebase before merge; each commit stays

Independent of that, Squash commits combines all commits of the merge request into one when merging (an option per project: do not allow, allow, encourage, require). Squashing gives one tidy commit per merge request, which suits conventional commits and easy reverts: the merge request title becomes the commit message (see Releases and Semantic Versioning). Keep the individual commits when they tell a story that reviewers or git bisect will need.

Also consider "Delete source branch when merged" (on), "Pipelines must succeed" (on), and "All threads must be resolved" (on). These three settings prevent most mistakes.

Merge trains

Imagine two merge requests that each pass their pipeline alone but break main when both land: they conflict in meaning although Git merged them cleanly. A merge train (Premium) solves this. Approved merge requests are put in a queue; GitLab tests each one as it would look after all merge requests ahead of it merged. If a pipeline fails, that merge request leaves the train and the ones behind it are re-tested without it.

The result is that main never contains an untested combination, even with dozens of merges a day. The cost is more pipeline runs, which makes pipeline speed (see Pipeline Efficiency Best Practices) even more important. Merge request pipelines (merge_request_event) must be enabled for it to work, and the pipeline needs rules that allow that source.

Habits for good merge requests

  1. Small and focused. Aim for changes a reviewer can understand in 15 minutes. A hundred-line change gets real review; a two-thousand-line change gets "looks good to me".
  2. A clear title and description: what changed, why, how it was tested, and a link to the issue (Closes #123 closes it on merge).
  3. Draft first. Mark a merge request as Draft while it is not ready, which also blocks accidental merges.
  4. Let the pipeline do the boring review. Linters, formatters and tests should comment first, humans review the design.
  5. Review within a day. A review queue that waits for days slows everybody. Agree on a service level and use CODEOWNERS to route (see Roles, Permissions and Protected Branches).
  6. Resolve threads and be kind. Comment on the code, not the person; use suggestions (the "Insert suggestion" feature) for small fixes.
  7. Keep main green. If it breaks, fixing or reverting it comes before new work. A revert button on a merged merge request creates the revert merge request for you.
  8. Use issue and branch naming: 123-fix-login-redirect links the branch to issue 123 automatically.

Stand-in: branch name and merge request checks

The first example is a linter for branch names and merge request titles, a typical small CI job for a team convention.

JS Branch and title linter

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second example models a merge train. Each merge request is tested on top of those ahead of it; a failure removes it and re-tests the rest.

JS A merge train

Press Run (or Ctrl + Enter) to see the console output here.

No output.

MR-4 never reached main because it clashed with MR-2 which was ahead of it. Tested alone, MR-4 would have passed.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which workflow keeps branches alive for only hours and hides unfinished work behind flags?

    Trunk-based development merges small changes into main many times a day and uses feature flags for incomplete features.
  2. 2. What problem does a merge train solve?

    Each merge request is tested on top of those ahead of it, so the combination that lands on main has been tested.
  3. 3. What does squashing do when a merge request is merged?

    Squash gives one commit per merge request, which keeps history tidy and makes reverts simple.
  4. 4. In GitLab Flow with release branches, where should a bug fix be committed first?

    The 'upstream first' rule makes sure a fix is never forgotten in newer versions.
  5. 5. Which habit best keeps reviews effective?

    Small changes can be understood and tested properly. Huge ones tend to be approved without real review.

Summary

  • Pick a workflow by release style: trunk-based for continuous delivery, feature branches as the default, GitLab Flow for environments or several supported versions.
  • Prefer short-lived branches, require pipelines and resolved threads, and delete merged branches.
  • Squash or fast-forward for tidy history; merge trains keep main green by testing combinations.
  • Write small, well-described merge requests and review them promptly.

Next: Project: A Web App Pipeline