Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 36 ยท Projects and Merge Requests

Branching Strategies and GitLab Flow

Compare trunk-based development, GitFlow and GitLab Flow, name branches and tags consistently, handle releases and hotfixes, and wire branches to environments.

Git lets you branch however you like, which means a team without an agreement ends up with chaos. A branching strategy is that agreement: which branches exist, how long they live, how work reaches production, and how releases and fixes are handled. GitLab publishes its own recommendation, called GitLab Flow, but you can implement any of the common strategies on the platform. This lesson compares the options and gives practical naming rules.

Why strategy matters

The right choice depends on how you ship:

  • A web service deployed many times a day wants short-lived branches and small merges.
  • A mobile app or on-premises product with versioned releases needs release branches and fixes for old versions.
  • Regulated environments need an auditable path from change to production.

Pipelines in GitLab can react to branch names, tags and merge requests (see variables and rules), so the strategy you choose directly shapes your .gitlab-ci.yml.

Three strategies compared

Trunk-based development. Everyone merges small changes into main (the trunk) several times a day. Branches live for hours or a day or two. Unfinished features are hidden behind feature flags. It needs good automated tests and gives the fastest feedback and the fewest merge conflicts.

GitFlow. A long-lived develop branch collects work, with feature/*, release/* and hotfix/* branches around main. It suits versioned products, but the many long-lived branches create painful merges and slow delivery, and most web teams find it too heavy.

GitLab Flow. Start from main with short-lived feature branches and merge requests, then add just what you need:

  • Environment branches (staging, production): code moves forward by merging main into staging, then staging into production. Each branch is what runs in that environment.
  • Release branches (1-4-stable) for products that support several versions: fixes land on main first, then are cherry-picked into stable branches ("upstream first").
flowchart LR
  F["feature branches"] -->|merge request| M["main"]
  M -->|merge| S["staging"]
  S -->|merge| P["production"]
  M -.->|cherry-pick fix| R["1-4-stable"]

Changes flow downstream in one direction. Fixes are made on main first so they are never forgotten in later versions.

For continuous delivery you can skip environment branches entirely and deploy from main through environments in the pipeline, using manual jobs for production.

Naming branches

A convention makes branches searchable and lets CI act on them. Common patterns:

  • <issue-number>-<short-description> (GitLab's own default when you create a branch from an issue): 42-fix-checkout-crash
  • feature/<name>, bugfix/<name>, hotfix/<name>, release/<version>

Rules of thumb: lowercase, hyphens instead of spaces, no personal names, short but descriptive. Delete branches after merging.

The stand-in below is a branch-name linter that you could adapt to a pre-push hook or a pipeline job. It accepts the two conventions above and explains what is wrong when a name is rejected.

Python Stand-in: lint branch names

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Releases, tags and version numbers

Mark released commits with tags. Use semantic versioning: MAJOR.MINOR.PATCH, where a breaking change bumps MAJOR, a backwards-compatible feature bumps MINOR and a fix bumps PATCH. Create tags in the web interface (Code, then Tags), or from the command line:

Terminal
git tag -a v1.4.0 -m "Release 1.4.0"
git push origin v1.4.0

GitLab can also create a Release object from a tag, with notes and attached assets, and a pipeline can run on tag creation (see the pipeline lessons). Protect tags matching v* so only maintainers can create them.

Python Stand-in: bump a semantic version

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Hotfixes

When production breaks:

  1. Branch from the production branch or tag (git switch -c hotfix/payment-timeout v1.4.0).
  2. Make the smallest possible fix, open a merge request, and let the pipeline run.
  3. Deploy, tag a patch release (v1.4.1).
  4. Merge or cherry-pick the fix back into main so the next release has it too.
Terminal
git switch main
git cherry-pick 9f3c2ab        # apply the fix commit to main

Forgetting step 4 is the classic hotfix mistake: the bug returns in the next release.

Choosing for your team

  • Deploy continuously and have good tests? Trunk-based, or GitLab Flow without environment branches.
  • Need to see exactly what is on staging and production? Environment branches or environment-based pipelines.
  • Support several released versions? Release branches with "upstream first" fixes.
  • Unsure? Start simple: main plus short-lived feature branches, protected main, squash merges. Add structure only when a real problem appears.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main idea of trunk-based development?

    Trunk-based development keeps branches short-lived and integrates into main often, relying on tests and feature flags.
  2. 2. What does GitLab Flow's 'upstream first' mean?

    Fixing main first ensures later versions always contain the fix.
  3. 3. A change adds a backwards-compatible feature to v1.4.2. What is the next semantic version?

    A backwards-compatible feature bumps MINOR and resets PATCH to 0.
  4. 4. After shipping a hotfix, what must you not forget?

    If the fix is not merged or cherry-picked into main, the bug comes back in the next release.

Summary

  • A branching strategy is a team agreement; choose it based on how you release.
  • Trunk-based development favors small, frequent merges; GitFlow suits versioned products; GitLab Flow adds environment or release branches only when needed.
  • Name branches consistently; GitLab's issue-based default is <number>-<description>.
  • Tag releases with semantic versions and protect release tags.
  • Hotfix from production, then bring the fix back into main.

Next: Pipelines and the .gitlab-ci.yml File