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.
If you prefer to jump straight into a specific section within the article, feel free to use the links on the right!
Branching Strategy with Releases
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 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 Branch creation
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:
There is one additional tab in the view, called
Releases, which will show any release branches created.Users have the option, after selecting open PR features, to either promote them directly to the (Main/Master) branch as with any other environment, or to create a release with these features included.
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, 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 release name you 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 section 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: You can configure validations to run automatically only on PRs which are merged into releases and not on an environment's individual feature PRs by configuring the Run validations on final environment setting when creating or editing a pipeline.
The pull request for the release branch is shown in VCS with all the included features referenced for auditability.
Note - Once changes have been merged into a release, no additional changes to the base feature branches will be brought into the release automatically. See What happens if I add extra commits to the original feature branches that make up the release? for more details.
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. This is so that features can be tracked reliably in Gearset without being corrupted by third party plugins such as Jira bot.
Abandoning a Release without promoting it
If a user wants to close a release without promoting it, select the release, and click the cog 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.
Note: Abandoning the release won't affect the features in the release PR in any way, but if you happen to have multiple PRs from the same source branch as part of the release, we'll only reopen one of them with all relevant commits.
Adding features to a 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.
Then select which release to add the features to. Next, 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 you can select View release in the main pipelines UI - to view what's in your release PR.
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.
Merging features into a Release
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 the remaining features into the release branch.
To do this hit the Resolve button:
And from the below panel accept which change is needed:
Once the merge conflict is resolved, you can add the feature to the release. To do so, select Merge into 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 (as shown on the screenshots below).
Example of adding a feature from the Releases panel:
Scheduling a Release
You can schedule a release to be deployed.
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.
Note: If the environment is blocked at the time of release, Gearset will reschedule the release for 5 minutes later and a warning will be shown. If the deployment fails an error will be shown.
Automatic tagging of Releases
Gearset will automatically tag releases with the release name, making releases easier to search in your Repository. It also makes it easier to:
See whether there are any changes that have been merged to master but haven't been deployed yet.
Review everything that was deployed in the previous release.
Other 'Release' related questions
In this section we're addressing other questions about features and functionalities that users often ask us about.
What happens if I add extra commits to the original feature branches that make up the release?
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.
Is it possible to remove a single PR from the Release?
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.
Is it possible to rename a Release package (PR)?
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.
Note about back propagation after Release deployment
As of now, when you deploy a "Release" to the final environment, it won't be creating a single PR to back propagate. Instead, it will back propagate all individual PRs which you have used to build the Release 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.
Moving to a different data region
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 an error when adding features to an existing Release?
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.
Explanation:
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.
