Gearset Pipelines supports two branching models: the expanded branching model and Gitflow. New pipelines use the expanded branching model unless you change Branching strategy in the setup wizard. This article compares the two models side by side, so you can choose one, and so you know which rules apply to the pipeline you already have.
For the full detail of each model, see The Gearset Pipelines expanded branching model and The Gitflow branching strategy in Pipelines.
Which branching model should I choose?
The expanded branching model and Gitflow suit teams that plan releases differently:
Choose the expanded branching model if each feature needs to move through your environments on its own, or if you often hold back or remove a feature late in a release cycle.
Choose Gitflow if your team integrates work early and releases on a set cadence. In Gitflow, work merged into
developis production-bound, and every release includes everything indevelop.
Gitflow isn't the right fit if you regularly need to hold back features close to a release date. Some Pipelines features aren't available in Gitflow yet, including Continuous Delivery Rules, long term projects, and automatic sync PRs. See Gitflow in Pipelines FAQs for the full list.
For more on that choice, see An introduction to Gitflow. For a wider view of branching strategies, see our blog post Choosing the right Git branching strategy for your Salesforce team.
How do the expanded branching model and Gitflow differ at a glance?
This table compares the expanded branching model and Gitflow on each topic covered in this article.
Topic | Expanded branching model | Gitflow |
Long-lived branches |
|
|
Feature branches are created from |
|
|
How a feature moves | A promotion PR into each environment in turn | Merged once into |
Releases | Optional. You choose which features go in | Required. One release at a time, with everything in |
Hotfixes | A developer sandbox linked directly to production | A branch from |
Back propagation | Automatic pull requests to earlier environments | Manual, with |
Sync PRs | Bring | Bring bug fixes and hotfixes back into |
Fixing a feature that's already been promoted | A fix PR, from the first environment | A bug fix PR against the open release branch |
Long term projects | Available on Automation Enterprise | Not available |
Which branches does each model use?
In the expanded branching model, each static environment has its own long-lived environment branch, kept in sync with its org by a CI job, and main is the branch for production. You create each feature branch from main, or from the project's base branch in a long term project. Gearset then creates a promotion branch for each feature and environment, named gs-pipeline/<feature-branch-name>_-_<env-branch-name>, so that merge conflicts are resolved without changing the feature branch.
In Gitflow, there are two long-lived branches: main for production, and develop for integration. There are no environment branches and no promotion branches. You create each feature branch from develop, and it merges only into develop. When you open a release, Gearset creates a short-lived release branch named gs-gitflow-release/<GUID>, where <GUID> is a unique ID that Gearset generates for each release.
Note: Gearset manages every branch whose name starts with gs-. Do not commit to these branches directly. Gearset Pipelines expanded branching model FAQs lists each gs- prefix and what creates it.
How does a feature move through each model?
In the expanded branching model, a feature moves through the pipeline one environment at a time. You promote its pull request into each environment, and after each merge Gearset opens the pull request for the next environment. Each feature moves on its own, so one feature can reach production while another waits.
In Gitflow, a feature's pull request merges into develop, and that's the end of its own journey. A counter on the Integration environment shows how many merged pull requests are waiting for the next release. The feature reaches production as part of a release.
Note: Both models support merge commits only. Squash, rebase, and fast-forward merges break the shared history between branches and cause unexpected merge conflicts later.
How do releases work in each model?
In the expanded branching model, a release is optional. You select open pull requests in the final environment and click Create release.... Gearset merges those features into one release branch, closes their pull requests, and opens one release pull request. Teams on Automation Enterprise can also build a release candidate in the environment before production. You can add features to a release, or remove them, before it's deployed. See Releases and release candidates in Pipelines.
In Gitflow, every change except a hotfix reaches production in a release, and only one release can be open at a time. A release includes everything merged into develop, so you can't pick individual features. If your pipeline has a Release & Testing environment, deploy the release there first, then open its pull request against main and deploy it to production. See Creating a release in your Gitflow pipeline.
How do I make a hotfix in each model?
In the expanded branching model, add a developer sandbox to your pipeline that links directly to production, to act as your hotfix environment. Create the hotfix as a new feature from that sandbox and promote it straight to production. After it's deployed, Gearset opens back propagation pull requests to your earlier environments. See Promoting your first features in Gearset Pipelines.
In Gitflow, a hotfix branch is created from main and merged into main. You can link a hotfix developer sandbox to production, or create the branch from main with compare and deploy and open a pull request against main. After the hotfix is deployed, sync it to develop and to any open release yourself. Gitflow doesn't do this automatically. See How to make hotfixes after a production deployment in a Gitflow pipeline.
How does back propagation work in each model?
In the expanded branching model, back propagation is automatic. When a change is promoted into the final environment, Gearset opens pull requests that carry it back to your earlier static environments, and to developer sandboxes that have back propagation turned on. Gearset creates these pull requests but doesn't promote them, unless you set up a Continuous Delivery Rule for back promotions. See Getting started with Continuous Delivery Rules in Gearset Pipelines.
In the expanded branching model, also merge the sync PRs that bring main into each environment branch after each production release. New pipelines create these automatically. See Keep your pipeline environment branches in sync.
In Gitflow, there's no automatic back propagation. When you fix an open release, or deploy a hotfix to production, click Create sync PRs on that environment and promote the sync pull requests it opens. Until you do, develop doesn't have the fix. See How to forward fix an open release branch in a Gitflow pipeline.
How do I fix a feature that's already been promoted?
In the expanded branching model, new commits on a feature branch reach its pull request only while that pull request is at the first environment. A pull request further along is marked stale and blocked. To update it, commit to the same feature branch, create a fix PR from your developer sandbox against the first environment, and promote the fix PR through the pipeline. See Fix forward: what's changing in Pipelines.
In Gitflow, fix forward doesn't apply. To fix a release while it's in testing, create a bug fix from the release in the pipeline and open its pull request against the release branch. Then sync the fix back to develop. See How to forward fix an open release branch in a Gitflow pipeline.
What are the common mistakes with each model?
These mistakes apply to the expanded branching model:
Creating a feature branch from the wrong branch. A feature branch created from another feature, a release, or an environment branch carries that branch's commits with it, so unrelated pull requests are marked as merged and deployed. Always create feature branches from
main, or from the project's base branch in a long term project.Skipping sync PRs after a production release. Environment branches drift from
main, and new pull requests show items you didn't change. Merge the sync PRs after every production release, before opening new pull requests.Expecting new commits to reach later environments. Pushing to a feature branch, by hand or from a script, only updates its pull request at the first environment. Use a fix PR for anything further along.
Merging pull requests in your Git provider. Pull requests merged outside Gearset can appear out of order in
Promotion history, and a stale pull request merged there doesn't include its fix. Promote in Gearset.
These mistakes apply to Gitflow:
Expecting to hold back a feature. A release includes everything in
develop. If you need to leave features out, Gitflow isn't the right model. Consider the expanded branching model with releases.Skipping sync PRs after a bug fix or hotfix. Bug fixes on a release branch, and hotfixes on
main, don't reachdevelopuntil you useCreate sync PRs.
These mistakes apply to both models:
Using squash, rebase, or fast-forward merges. Use merge commits only.
Committing directly to a
gs-branch. Gearset manages these branches, and direct commits cause unexpected behavior.
