The Gearset Pipelines Branching Model is great for keeping features isolated from each other as they progress through your environments but still allowing a bundling of those features into a release at the end. However, we understand some customers have longer-term projects that require building on work that may not have passed all the way through to main yet, and sit in various testing stages for longer periods of time before releasing as 1 slice to move forward towards Production. This could be with completely isolated projects, or teams developing in a more GitFlow way of working, keeping development deliberately separate from slower release cycles.

To help with this different workflow, we're announcing a new feature which will allow a 'Project' to be added into your Pipeline alongside the Developer sandboxes and Static environments (CI Jobs) that make up your main workflow. This project acts as a 'sub-pipeline', allowing you to populate it with its own sandboxes and workflow, but still feed into your main pipeline at the right stage.

You can add in a new project in the same way you add a new sandbox/environment to your Pipeline, and the only information needed is the project name, base branch to create new features from inside the Project and whether you'd like to allow back propagation PRs to open into the final environment.

The base branch should match the final static environment in the project, as that’s where we release from into the main pipeline. If the last environment branch in the long term project does not match your base branch, you will not be able to connect your project to the pipeline.

Below we can see a 'Quarterly Release Project' with a few environments inside and a dedicated branch 'Project1' associated with it, feeding into my Integration environment, alongside the usual stream of work from developer sandboxes. This means I could have fast-moving changes heading through testing cycles and towards production via the developer sandboxes, while project work can continue uninterrupted in Project1 until we're ready to release.

You use the blue arrow to head into the project itself and add/edit environments as you normally would. This allows you to set up the right sandbox structure to help accomplish your project. We can see below that I've got a shared sandbox and synchronisation job, connected into the main Project1 integration sandbox which acts as my final environment. Features can progress and build up in that final environment until I'm ready to release into my main Pipeline, and also receive back propagations that may have passed into production through the main work stream, like BAU features or hotfixes.

When building your long term project and first adding your environments, this will not automatically link to the main pipeline, and you will see something like:

To connect your final environment to the main pipeline so that your project integrates correctly, make sure the final environment in your project is connected like so:

This will then show like below in your project, and changes from your project will feed to the main pipeline, and back propagation from your main pipeline will feed into your project (if enabled):

If the environment branch is not the same as the base branch for the project, you will see a red circle rather than a green one when connecting the environment to the pipeline.

When thinking about syncing environments; you will be able to sync Project1 from Main to align the history, and then open Sync PRs from your Project1 Base branch into the preceding sandbox environments, which will make sure new features cut are completely aligned and not showing unexpected commits. You could also back propagate individual PRs in the usual way.

Once all the features are in the Project1 branch and are ready to release, you can click on the final link to get back to the main pipeline and select your project folder, which will allow you to create a new pull request into the next connected environment. This creates a 'release' of the built up features to then progress through the rest of the sandboxes, and be treated as any other feature would with merge conflict checks, validation, status checks from your source control system, and a breakdown of files changed for pipeline owners to review. The branch naming convention to identify a project release is:

Below we can see a PR with the branch 'gs-project/ef0a254d-778d-4386-93cd-713024fefbcf'. Also note the project name on the list of open PRs.

The project release can now progress through the final testing phases before being merged into main and deployed to Production, and being made available as a back propagation PR to the other environments.

A workflow diagram summarising the procedure to release from a long term project is shown below:

You can now also see the included tickets (JIRA or ADO) merged into your Project Branch when clicking the project to create a release, and even attach more tickets in if needed (like Epics to encompass the full release).

As we know with any feature/release, sometimes there can be failures found in various testing phases. In the example above, what if one of the features that built up into my project release was found to have issues in the Integration environment and required extra commits to resolve the problems? This might be due to failures identified by testers, integration issues with external systems, or any number of issues we don't find out until after we release to the next environment in the main pipeline.

Our other document on 'edit or fix a user story in progress in pipelines' explains how this functions for individual features, but considering the feature branches will close upon merging into the project branch and back propagating to the rest of the project, that route wouldn't be viable. See below for some specific recommendations on how to achieve this in Long Term Projects: