Long term projects in pipelines

An overview of the new functionality to handle Long term projects in Gearset Pipelines and how that will affect your workflow

Samuel Crossland avatar
Written by Samuel Crossland
Updated this week

What license do I need to use this feature?
The use of Long term projects is tied to the Automation Enterprise tier only.

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.

How do Long term projects work?

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.

Connecting your long term project to the Pipeline

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.

Syncing and releasing

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.

Note: Since feature branches will be created from Project1 rather than main, this means all other in-flight features (commits) present within that branch will be tightly coupled together and not isolated from each other as they are in the Pipelines Branching Model. This is something to be conscious of when working in this way vs cutting features from main.

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:

  • 'gs-project/<GUID>'

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.

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).

What if I need to get more commits into a project 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:

  1. Take note of the 'gs-project/<GUID>' branch name referenced above in an open PR. This acts as the base 'release' branch for the project and our target for any extra items needed.

    1. Note - anything starting 'gs-pipeline/' is actually a promotion branch for a specific environment so we don't want to use those here unless solving specific merge conflicts.

  2. Using Gearset Compare & Deploy (C&D), we can find the specific 'gs-project/<GUID>' branch as a target, and then look to add extra components in from a particular sandbox. It may be best to do this from a sandbox present inside the Long Term Project to ensure it contains the relevant baseline metadata.

  3. Work through the C&D stages to select new updates/fixes required, review any Problem Analysis results, link in any tickets relevant (always a good idea considering you're modifying a full project release) and then commit into that branch.

  4. You can now open up a new Pull Request to the environment branch where your testing failed (e.g Integration in the screenshots and scenario referenced above) to redeploy the extra elements into the sandbox.

    1. You may have seen the extra commits update against any open promotion PRs for the release (in branches 'gs-pipeline/gs-project/<GUID>_-_<TargetEnvironment>'), but not automatically deploy into the environment you're testing in. For example, the project release was already PR'd against UAT so I can see the extra commits sync into there, but I also need to take them back into the Integration environment where the testing failures occurred.

  5. Pipelines will detect that new PR targeting an environment branch, convert it to a promotion branch, showcase only the delta commits you've added in, and conduct the usual merge conflict/validation checks.

  6. Once you're happy with the status, promote that PR in Pipelines and the CI job will deploy the extra components into the sandbox for retesting.

  7. Since the extra commits will have already synchronized into any open PRs for the project release (e.g to UAT as the next environment along), once you've confirmed the testing again you can continue promoting as usual from your original PR.

  8. When that release is deployed through the full pipeline and into Production, the back propagation PR will then contain all commits as part of the release, including the extra ones you added to gs-project/<GUID> to resolve testing failures.

Did this answer your question?