This document describes the current slice of Gitflow available in Gearset Pipelines. We’re continuously expanding and refining the experience. If you have any feedback, we’d love to hear from you via our in-app chat.

Gitflow Branching Model

Gitflow is a branching strategy designed to support structured development, controlled releases and clear separation between ongoing work and production-ready code. Below is the current version of the Gitflow branching model in Pipelines:

Gitflow is built around two long-lived branches:

main (or your respective production branch) contains production-ready code.
develop (or your respective integration branch) is the primary integration branch for ongoing development.

Unlike the current Pipelines expanded branching model, Gitflow does not use long-lived environment branches for each static environment in your pipeline. Instead, all work flows through develop, and temporary branches are created for features and releases before the release is merged into main.

How It Works

Users create feature branches from develop to work on new changes.
Once completed, they merge their feature branches back into develop.
When preparing for a release, a release branch is created from develop for final validation and testing. This release branch typically includes all features in
develop, rather than selecting individual PRs to include.
Once ready, the release branch is merged into main.

Your team decides which Salesforce orgs map to which branches. For example:

develop may deploy to an Integration, SIT or QA org.
Release branches may deploy to UAT or Staging for final validation before merging into main and deploying to production.

Setting Up a Gitflow Pipeline

Create a new pipeline

If you already have an existing pipeline, go to your pipeline selection in the top left corner and choose Create new pipeline:

If you do not have any pipelines, choose Create a pipeline on the landing page:

Select the Gitflow branching strategy

You’ll first see the default expanded branching model. To switch:

Select Change under Branching strategy:

Choose Gitflow and continue through the setup wizard:

Integrate issue tracking (optional)

You can connect Jira or Azure DevOps, provided connections are already configured:

Configure pull request requirements

You can require pull request descriptions and choose whether reviewer settings should be copied between environments:

Select your VCS provider

Gitflow supports the same providers as existing Pipelines except AWS CodeCommit:

Choose or create your repository

If you’re adopting Gitflow for the first time, we recommend starting with a new repository so that your long-lived branches begin in sync.

Enter a repository name and Gearset will create it in your VCS:

You will then select:
- Your production branch (typically main or master).
- Your integration/develop branch, the source for new features and the integration point for ongoing work.

We recommend letting Gearset create a new integration/develop branch from main:

You can give this branch a name:

Populate your repository

You can either:

Allow Gearset to auto-detect metadata to include, or
Choose a saved metadata filter.

Once your metadata is selected, you can create your Gitflow pipeline:

Adding Environments to the Pipeline

When your pipeline is created, it contains three sections:

Integration
Release & Testing
Production

Integration Stage

This stage is for developer sandboxes and one static environment (in the current slice) that receives work merged into develop.

Adding a static integration environment

Select Add environment in the Integration section, or choose + Add → Add static environment:

Choose to create a new CI job or select an existing one:
- The job must use your designated integration/develop branch as its source branch.
- Existing jobs must meet the conditions shown (typically those created from a previous Gitflow setup).
Name the environment and select the target org.

Adding developer sandboxes

Select + Add → Add developer sandbox:

The instructions are the same as outlined here.

Release & Testing Stage (Optional)

This stage contains the release and any static environments where release branches are deployed for validation and/or testing.

You can add one static environment here using the same process as above. However, you must create a new CI job.
Unlike the expanded branching model, you do not pick a source branch for this environment’s CI job. Gearset automatically handles the creation and deployment of any short-lived release branches.

Once you add a static environment in this stage, you may see a branch in your VCS named gs-gitflow-baseline-release.

Gearset creates this branch to run a baseline CI job, allowing your release branch deployments to benefit from Delta CI. If you need to delete and recreate the release environment, you must first delete this baseline branch in your VCS before creating a new CI job.

In all other cases, this branch should not be edited or removed.

Production Stage

Add your production environment using the same process as above.

Creating and Promoting Your Features

Most development and promotion activity happens in the Integration stage.

The process is largely identical to Pipelines today as outlined here (up until the Next steps: after a feature has made it to Prod).

Working with feature branches

Teams can:

Create feature branches directly from develop in their personal or shared sandboxes.
Link Jira/ADO tickets to feature branches.
Commit changes and create a pull request (PR) back into develop.

PR creation works similarly to existing Pipelines, but with an important difference:

There are no promotion branches in Gitflow. The expanded branching model uses promotion branches to isolate feature branches and prevent pollution (largely due to merge conflict resolution) as they move through environments.

Gitflow does not require this because feature branches only merge back into develop, never downstream into multiple environment branches.

Promoting pull requests

Gearset provides the same automated checks available in Pipelines today:

Merge conflict checks
Validation deployments
Running Apex tests
Third-party test integrations
Respecting VCS review and approval rules
Viewing commits, files and linked tickets

Once checks and reviews are complete, users promote the PR to the static integration environment to integrate their changes with other in-flight work.

In Gitflow, developer sandbox updates happen when a PR merges into your designated integration/develop branch, not main as in the expanded model.

When PRs are promoted, the counter on the right side of the Integration environment increases to show how many merged PRs are waiting for the next release:

Creating a Release

To open a release, you can:

Select the PR counter to the right of the Integration stage, or
Select the Integration environment and open the Release creation tab.

Selecting PRs for the release

In Gitflow, releases typically include all changes merged into develop. This means you cannot pick individual PRs for the release.

However, Gearset allows you to exclude recent PRs in a linear sequence starting from the most recent one. In the example below:

You can select all PRs up to PR #3 by selecting it. This means PRs #4 and #8 will be excluded from the release (greyed out):

If this does not apply to you, then you do not need to take any steps here.

Once ready, click Create release:

Naming and opening the release branch

You can choose a release name (unless you have configured a release naming convention in your pipeline settings) and view a summary of included features:

Select Create release to open the release branch. The name of the release will now appear on the node in the Release & Testing stage:

Viewing and Validating a Release

After a release branch is created, Gearset automatically runs a validation on the testing org linked in the Release & Testing stage (if applicable) giving early warnings about potential failures.

Viewing the open release

If you click on the release name, users can view:

The features included in this release
Linked Jira/ADO issues
All changed components

If a static environment is configured for this stage, you must deploy the release to this org before creating the PR against main.

Deploying to the release testing org (if applicable)

By clicking the name of the static environment, you can:

View validation results
Review features and commits
Confirm linked work items

Once satisfied, select Deploy release to deploy the release branch to your testing org. You will see a record of that deployment in the Deployment history tab.

The source branch of the CI job is automatically updated when a new release is created, so that the promotion history is preserved between releases.

Gearset continues to use Delta CI, if enabled, to deploy only the net-new changes in current release instead of redeploying the entire branch.

Deploying a Release to Production

After successfully deploying the release to your test environment, you will see a “Ready to promote” banner appear on the release node.

Open the release node and choose Open pull request to open the PR against main:

Once the PR is opened, Gearset will run:
- Merge conflict checks
- Final validation steps
- Any required VCS review rules

Similar to the current releases view in Pipelines today, users can see:

All features included
All linked issues
All changes included in the release

Once satisfied, select Deploy release to promote the release to production. Once the PR is merged into main, your release is complete.

FAQ

1. How do I abandon my release?

You can abandon a release at different points depending in your pipeline.

The release PR has not be opened against production

Open the release node and select the Abandon button:

Choose whether you want to delete the release branch, then select Abandon to confirm:

The release PR is already open against production

Select your production environment and open the Releases tab:

Select the menu next to Deploy release and choose Close release PR:

The release will still appear on your release node. If you want to fully abandon it, follow the steps in The release PR has not been opened against production.

2. What do I do if I need to make a fix on my release branch?

This workflow will be brought into the Gitflow Pipelines UI in an upcoming slice of work. The following steps are the recommended interim approach.

Sometimes issues are discovered during testing of a release branch, such as failures in UAT, unexpected integration behaviour, or missing components. In these cases, you may need to add more changes to your open release.

There are two recommended approaches:

C&D: Direct Commits

1. Note the name of your release branch (gs-gitflow-release/<GUID>) shown at the top of the release node. This is the branch you will commit to:

2. Using Gearset’s C&D, select the release branch as your target, and use a sandbox (ideally one from your Integration stage to ensure the correct metadata baseline) as the source:

3. Work through the C&D flow:

Select the required fixes
Review any Problem Analysis results
Link tickets if needed
Commit the changes into the release branch

After committing:

The new commit will appear in the Changes tab of the release:

You must redeploy the release to the Release & Testing environment so it includes the new changes that you’ve committed.

In this method, your changes are not validated before committing them into the release branch. The release will only be automatically re-validated after the changes are committed to the branch.

C&D: Pull Requests

If you'd prefer to validate changes before merging them into the release branch:

1. Follow steps 1–2 above, but before selecting Compare now, choose Create new branch from gs-gitflow-release/<GUID> and give the branch a name:

2. Work through the C&D steps and commit to this new fix branch.

3. Select Create pull request:

4. Enter your pull request details and select Create pull request, ensuring the PR target is your release branch (gs-gitflow-release/<GUID>).

Your PR will appear under Open pull requests for the release environment and will automatically be validated (as if it were combined with your release branch). After validation, promote the PR to merge your changes into the release branch:

You can also perform the above workflows directly in your VCS/CLI.

Syncing changes back to your integration branch

Any additional commits added to a release branch must be synced back to your designated develop/integration branch to ensure they are aligned.

To create a sync PR:

1. Select the static environment in your Release & Testing stage and choose Create sync PRs:

2. Select Create pull requests:

You’ll now see a sync PR opened against your Integration environment:

3. What do I do if I need to make a hotfix to production?

The ability to link a dedicated hotfix sandbox to production, similar to current Pipelines, is coming soon.

In the interim, you should follow the workflow described above for creating PRs against main. We do not recommend directly committing to this branch.

Syncing hotfix changes back upstream

You can do this by creating a sync PR from the release environment:

1. Select your Production environment and choose Create sync PRs: