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.

If you prefer to jump straight into a specific section within the article, feel free to use the links on the right!

When utilizing Releases in Pipelines, the branching strategy behind it changes somewhat to incorporate a release branch concept used to optionally bundle 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 how 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 final environment in a pipeline.

In the pipelines UI, the final environment differs from other environments in two ways:

To create a release, select at least one open feature from the Open pull requests tab and click Create release...:

On the subsequent pop-up window, enter the release PR name for this release. Optionally, you can schedule the deployment of this release on creation - this allows you to deploy releases at whatever cadence you require.
​

You can specify a default release PR naming scheme for a pipeline by navigating to that pipeline's settings (Settings cog -> Edit pipeline settings), and by going to the Releases tab.

Once you click Merge into release, Gearset will create a new release branch from the base branch configured for that pipeline (usually the main or master branch). We then merge the selected feature pull requests into that new branch, close those feature PRs, and open a new pull request from the release branch to the target environment branch. The release PR created will have a name corresponding to the name specified when creating the release in Gearset.
​
The release will be created so long as at least one feature could be added successfully. Any features which were unable to be added to the release (due to conflicts) will need to be manually resolved and merged into the release. For more information see [the below section on merging features into releases](https://docs.gearset.com/en/articles/6963012-releases-in-pipelines#h_a4baafb89b)
​

The Releases tab shows information about all the changes included in the release, as well as any associated information such as tickets or deployment steps. Validation statuses are also shown here, running on the release PR in aggregate to ensure that it will deploy successfully.

A release can be deployed to that environment by selecting it and clicking Deploy Release.

The pull request for the release branch can also be found in your VCS with all included features referenced.

If a user wants to close a release without promoting it, select the release, and click the 'more' icon - this stands for "Abandon release".

It 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. Alternatively, you can find the release in the Releases tab and select Add to release.

Both options display the release pop-up in the pipelines UI. Here, you can specify which release to add features to, and what features to add. The Merge into release button will then add them to the referenced release branch.

To remove features from a release, you will need to abandon the release and reopen it using the same set of feature PRs, minus any features you wish to remove.

Sometimes, multiple features being added to a release will conflict with each other or the release branch in aggregate. 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 the remaining features into the release branch.

To do this hit the Resolve button:

And from the below panel accept which change is needed or it will also keep the previous resolution checked if it was enabled:

Once the merge conflict is resolved, you can add the feature to the release. To do so:

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 (as shown on the screenshots below).

Example of adding a feature from the Releases panel:

You can schedule a release to be deployed. Either in the initial creation of the release, or as shown below.

To do this, select the Schedule deployment in the drop-down menu.

This opens the model, allowing you to select a date and time for the deployment.

Once it has been set up, the deployment of the release will automatically run at the set time. You can see the scheduled release information in the Releases panel:

You can still add features to the scheduled release.

Gearset will automatically tag releases with the release name, making releases easier to search in your Repository. It also makes it easier to:

In this section we're addressing other questions about features and functionalities that users often ask us about.

When a feature is merged into a release branch, it should be in a tested, verified and ready-to-release state. Due to this, unlike the classic promotion branch behavior explained here, Pipelines won't automatically layer on extra commits made to the original feature branch into a release branch.

To include these changes in a release, you will need to abandon and recreate the release branch (see Abandoning a Release without Promoting it section) with the correct feature branches containing those extra commits.
​
If you promote the release branch before abandoning/recreating to include the new changes to the feature branch, a Sync PR will open against that final environment to pull in the missing changes.
​

Unfortunately, not. Gearset doesn't offer such option.
​
If you need to remove a single PR from your Release package, you'll have to abandon the entire Release and then re-create it without the PR that needs to be excluded.
​
We're aware we have received feedback (from other users) on our UserVoice forum about such functionality - you're welcome to add your comments and vote for this feature request.

You can rename the release manually in your Git provider. This cannot be done in Gearset app.

Alternatively, you can abandon the release and re-create it with a new name. Read more about abandoning the release here.

When promoting a release in Pipelines, the following steps occur:

Back Propagation Releases will back-propagate releases as a single PR.

As a best practice we recommend syncing up all environments to your default base branch (main/master) after a release. This is to prevent unexpected differences in future pull requests.

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.

Do you see below error?

Gearset couldn't merge these features into the release branch automatically due to a feature tracking failure. Please contact us via the in-app chat for help with this issue.

You're probably trying to add features while being 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.