Use Cases

  • Teams with multiple deployment environments (staging, pre-production, production)
  • Projects requiring gated promotion through environments
  • Any team on any platform (not GitLab-specific)
  • When you need a staging safety net without Gitflow's full complexity

Components

  • main (main-branch): Integration branch — reflects current development, deploys to staging on merge
  • environment branches (supporting-branch): Downstream branches representing deployment targets (staging, pre-production, production). Only receive merges from upstream — never merged back.
  • feature branches (supporting-branch): Short-lived branches for features or fixes, branched from main
  • upstream-first policy (policy): All changes must exist in upstream branches before being merged downstream. A production fix must first land in main, then be cherry-picked or merged forward to production.

Steps

  1. Step 1: Create feature branch from main: Branch from main (the integration branch) to develop a feature or fix
  2. Step 2: Develop and open merge request: Commit to feature branch, open a merge request targeting main
  3. Step 3: Merge to main: After review and CI passes, merge feature to main. This triggers a deploy to the staging environment.
  4. Step 4: Test on staging: Automatic or manual testing runs in staging (which tracks the staging branch or main directly)
  5. Step 5: Promote to pre-production: Merge main into the pre-production branch to deploy to the pre-production environment
  6. Step 6: Promote to production: Merge pre-production into the production branch to release. Tag the commit.
  7. Step 7: Handle production hotfixes upstream-first: Fix the bug in main first, then cherry-pick the fix forward to production. Never commit directly to a downstream branch.

Workflow Diagram

gitGraph commit id: "initial" branch staging checkout staging commit id: "staging-base" branch production checkout production commit id: "prod-base" checkout main branch feature/login checkout feature/login commit id: "add login" commit id: "fix tests" checkout main merge feature/login id: "merge feature" checkout staging merge main id: "promote to staging" checkout production merge staging id: "release v1.0" tag: "v1.0"
Step 1 of —

Common Gotchas

  • Flow direction is non-obvious and often implemented backwards: The most common mistake is merging staging back into main (reverse of correct direction). Code always flows main → staging → production, never backwards via regular merges. critical
  • Production fixes require upstream-first discipline: An urgent production bug must be fixed in main first, then cherry-picked to the production branch. Directly committing to production creates a divergence that will conflict later. critical
  • Environment branch proliferation: Each environment (dev, qa, staging, pre-prod, production) needs its own branch, which multiplies the number of branches and promotions to manage important
  • Requires environment parity: Bugs that only reproduce in production (not staging) suggest environment divergence, which undermines the value of the staged promotion model important

Best Practices

  • Enforce the upstream-first rule — no one commits directly to environment branches
  • Automate promotion merges with CI/CD pipelines (e.g., merge to staging on main push)
  • Use cherry-pick for backporting fixes, not reverse merges
  • Keep main always deployable to staging at any moment
  • Tag releases on the production branch, not main
  • Use environment-specific configuration via CI variables, not code branches

Pros and Cons

Pros

  • Clear, unidirectional promotion path from development to production
  • Staging safety net without Gitflow's release branch overhead
  • Platform-agnostic — works equally well on GitHub, Bitbucket, or GitLab
  • Integrates naturally with environment-specific CI/CD pipelines
  • Hotfix process is explicit (upstream-first cherry-pick)

Cons

  • More branches and merge steps than GitHub Flow
  • Upstream-first rule requires team discipline to maintain
  • Slower path to production vs. direct GitHub Flow deploys
  • Environment drift is still possible if promotion is not automated
  • Two variants exist (environment branches vs. release branches) which causes confusion about what "GitLab Flow" means

Real-World Examples

  • GitLab Inc.: GitLab itself uses GitLab Flow for its SaaS product. Engineers merge features to main, which deploys to staging.canary.gitlab.com before promotion to production. Critical for their continuous delivery model where hundreds of engineers contribute daily.
  • Any multi-environment SaaS team: Teams running dev → staging → production pipelines adopt this pattern as a middle ground between the simplicity of GitHub Flow and the structure of Gitflow. Common in organizations that have been burned by direct-to-production GitHub Flow deployments.