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.
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 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 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 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: 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.
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 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.
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 - “Abandon Release”. This will close the release branch and re-open any feature branch pull requests which were included in the release.
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.
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.
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 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.
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 time and date 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 release 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. Making it easier to:
See whether there's any changes that have been merged to master but haven't been deployed yet.
Review everything that was deployed in the previous release.
Note about Back propagation.
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 be 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 (main/master) after a release 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.
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.
