Different teams work with Pipelines in a variety of ways, particularly when it comes to releasing changes into Production. Some teams push changes through feature by feature all the way to Production, releasing on demand, while others release on a set cadence (e.g. every one or two weeks) or bundle features together to release in blocks. For cadence-based releases, we now provide the ability to merge multiple features into a release branch, which can be checked for merge conflicts, validated and then promoted into Production. This article describes how this process works.

Note: As best practice, it's recommended to manage and promote releases in Gearset rather than in your version control system.

When utilizing Releases in Pipelines, the branching strategy behind it changes somewhat to incorporate a release branch concept to bundle those features together.

The diagram below shows how a release branch is carved out of your main branch (when following the rest of this guide) and features can then be merged into it, which provides Continuous Validation against your Production org and the ability to merge it into Main and deploy to Production when ready.

Release branches can only be created on the last environment in a pipeline. In the Pipelines UI, this environment differs from other environments in two ways:

To create a release, select at least one open feature from the Open pull request tab and click “Create Release”.

On the subsequent pop-up window, choose a release branch name to create and select “Merge into release”.

Gearset will create a new release branch from the base branch configured for the pipeline, usually the main or master branch, with the name selected. We will then merge the selected pull requests into this new branch, close them and open a new pull request from the release branch to the target environment branch (also usually master). This will only complete if all branches can be merged into the release branch successfully - if this doesn't happen, you will need to create a release with a subset of the features and add to them using the "add to release" functionality (see below).

Clicking the view release button will close this dialog and show the Releases tab. This includes details of all the changes included in the release and the combination of components ready to deploy. Merge conflict checks and validation is also run on the PR to ensure it’s good to merge when ready. A release can be executed by selecting it and clicking “Deploy Release”.

Note: once changes have been merged into a release, no additional changes to the base feature branches will be brought into the release automatically. To include these changes in a release, you will need to abandon and recreate the release branch (see “Closing a release without promoting it” section below).

The pull request for the release branch is shown in VCS with all of the included features referenced for auditability.

Since 24/07/2023, for newly created releases, we'll store a release UUID in the release branch name and track features added to it. So that features can be tracked reliably in Gearset without being corrupted by third party plugins such as Jira bot.

If a user wants to close a release without promoting it, select the release, and click the cog icon - “Abandon Release”. This will close the release branch and re-open any feature branch pull requests which were included in the release.

After a release has been created, users can add more features by selecting an open pull request and choosing “Add to Release” from the promotion dialog. This opens up the release pop-up in the Pipelines UI.

Select which release to add the features to, and select "merge into release" to add them into the open release branch PR.

Once complete, you can select more features to add from the list of open pull requests, or view the release in the main Pipelines UI.

The additional features will then be shown as included in the release.

If it is desired to remove a feature from a release, you will need to abandon the release and reopen it using the new set of desired features.

Sometimes, multiple features being added to a release will conflict with each other or the release branch. If this occurs, we will attempt to merge as many features into the release as possible automatically, marking the other features as failing to merge.

Users can then resolve the conflicts within Gearset and then merge them into the release branch.

To do this hit the Resolve button.

Accept which side is needed.

Once the merge conflict is resolved then you can add it to the release.

If a feature has an identified conflict against the master branch so cannot be merged directly, but could still be required as part of a release (e.g. it is dependent on another feature in the release), this feature may be added to a release directly from the Releases panel.

As seen below, the feature cannot be merged or added to a release from the Open pull requests panel, but you can attempt to add it to the release from the Releases panel.

If you have created a pipeline and wanted to move to a different data region, make sure you abandon all releases in the pipeline first, as releases only work in the same data region they're created in. You'll need to recreate the pipeline along with the releases after the switch.

In addition, if you see the following error, you're probably trying to add features in a different data region to one the release is created in, e.g. release created in the EU data region and attempting to add features in the US data region. Please reach out to us via intercom with a screenshot and we'll be happy to help.