In GitLab Flow, what are environment branches and how do changes reach production?

## Where GitLab Flow starts GitLab Flow keeps the single-integration-branch idea — `main` is where work is merged — and adds long-lived branches that model *where code is deployed*, together with a rule about which direction changes travel. It is best understood as a middle position: less ceremony than Git Flow's develop/release/hotfix set, more structure than a lone `main`. ## What an environment branch is An environment branch is an ordinary long-lived Git branch whose name matches a deploy target: `staging`, `production`, sometimes `pre-production`. The names are conventions; Git attaches no meaning to them. What gives them meaning is a single invariant the team enforces: **the tip of the branch is what that environment is running**. That makes "what is in production right now" a question you answer with Git rather than with a deployment dashboard: `git log production`, or `git log production..main` for everything merged but not yet promoted. ## The downstream-only rule Changes enter at the top and move down. A unit of work is merged into `main`. Promoting to staging is `git merge --no-ff main` while on `staging`; promoting to production is the same merge from `staging`. Nobody commits to `staging` or `production` directly. The payoff is an invariant worth stating out loud in an interview: after a promotion, the promoted commit from `main` is an ancestor of the environment branch's tip, so nothing can be running downstream that has not already been integrated upstream. The moment someone commits straight onto `production`, that invariant is gone and no amount of tooling restores it. The branches are also naturally ordered by how far behind they are. `git rev-list --count production..main` is a live count of merged-but-unpromoted work. ## Upstream first, for urgent fixes An incident tempts you to commit the fix on `production` because that is where the problem is. GitLab Flow forbids this and calls the alternative "upstream first": make the fix on `main` (directly, or on a branch merged into `main`), then bring that one commit downstream with `git cherry-pick -x <sha>` onto `production`. The reasoning is purely about history. A commit made only on `production` exists nowhere else, so the next promotion merge brings down a `main` that never had it — and if someone later touches the same lines upstream, the merge either conflicts confusingly or quietly reverts the emergency fix. Fixing upstream first means the change is present on every branch that will ever be promoted, and the eventual promotion merge sees matching content and resolves cleanly even though the cherry-picked commit has a different hash. The `-x` flag matters here: it appends a line to the commit message recording which commit was cherry-picked, so the duplicate is traceable rather than mysterious. ## The release-branch variant GitLab Flow also describes a second shape for software that is versioned and shipped rather than deployed: instead of environment branches, keep a long-lived branch per released minor version, and apply the same upstream-first rule — the fix lands on `main` and is cherry-picked onto each supported version branch. The two variants are alternatives, chosen by whether your users run your deployment or their own copy. ## What Git is actually doing Nothing exotic. Environment branches are branches, promotion is `git merge`, upstream-first patching is `git cherry-pick`. Everything in the model is a convention the team enforces socially or with server-side checks; Git has no concept of an environment. That is precisely why the discipline matters: the invariant holds only as long as everyone keeps commits off the environment branches. ## When environment branches earn their place They pay off when promotion is a gated, deliberate step — an environment that deliberately lags, a manual sign-off, a deploy window — because then "what is on staging" is genuinely different information from "what is on main", and encoding it as a branch makes it queryable. They cost more than they return when every merge to `main` goes straight to production. In that case `main`, `staging` and `production` all point at nearly the same commit, and the branches are two extra merges that tell you nothing you could not read from `main` and a tag. ## The common failure mode A team adopts environment branches, then hotfixes directly on `production` during an incident "just this once". Weeks later the fix is gone, no one can say when it disappeared, and `git log production` no longer means what the team thinks it means. The model's value is entirely in the invariant; the invariant is entirely in the discipline.