Overview
One of the upcoming changes to Pipelines is the ability to queue PRs for promotion, even when another promotion is already in progress. This means users no longer have to wait for the current promotion to complete before actioning their PRs.
How it works
Promoting a PR
To kick off a promotion, a user selects their PR and clicks Promote changes:
The PR will move to the Promoting section under Now:
If other users wish to promote their PRs while a promotion is already in progress, they can still do so by clicking Promote changes. Their PRs will be added to a queue in a first-in, first-out (FIFO) order under Next:
Once the first PR has been promoted, the next PR will automatically be promoted. This carries on until the queue is empty.
If multiple PRs are selected for promotion together, they will be shown as a single unit in the queue:
Users can expand the unit to view all included PRs by clicking the v arrow:
Managing the queue
There are a few ways to manage the queue, with some actions available to all team members and others restricted to team owners (in case of a team-shared Pipeline):
Canceling a promotion
This can be done by clicking the three ellipses icon to the right of the PR and selecting Cancel promotion:
Note: Team owners can remove any user's PR from the existing queue as long as the promotion has not started. However, team members are able to only remove the PRs they have promoted.
Reordering the queue
Team owners can reorder the queue in two ways:
Clicking the three ellipses icon and selecting Promote next, which moves the PR to the top of the queue.
Moving the PR to any position using the drag handle to the left of the PR name.
Handling promotion errors
Case 1: Single PR
If a PR cannot be promoted, it will be removed from the queue, returned to the Open section and marked with an "X". If you select that PR, you will see a banner indicating that an attempt to promote these changes was unsuccessful:
For specific details about the error, click the View details… button within the banner. This will open a modal window containing the error information:
Case 2: Multiple PRs
When multiple PRs are selected and added to the queue as a single unit for promotion, and an error occurs, all PRs within that unit will be removed from the queue and returned to the Open section. Similarly, each PR that was part of that failed promotion will be marked with an "X":
If you select one of these PRs and view the error details, the modal will not only display the specific error, but also indicate the other PRs that were included in the attempted promotion. For example, if you tried to promote PR #1, #2, and #3 together and the promotion failed, each of these PRs will be marked with an "X" upon returning to the Open section. If you then select PR #1 and view the error details, the modal will state that you attempted to promote it together with PR #2 and #3. This same information will be displayed if you select PR #2 or PR #3:
Validations and the queue
Standalone validations occur either automatically when a PR is raised against an environment with the "Validate pull requests targeting…" setting enabled, or when a user manually triggers a validation. These validations are handled as follows:
The queue shown above the Open section is specifically for promotions and its associated jobs. Standalone validations are generally not shown in this queue.
The only instance where a standalone validation will appear in the queue is when it is currently in progress. In this scenario, the relevant PR will move under Now and display a "Validation Only" banner:
Once the validation has completed, the PR will move back to the Open section.
If one or more PRs are raised against the environment, or a manual validation is run, while a standalone validation is in progress, those PRs awaiting validation will be marked with a clock icon in the Open section. They will not appear in the queue itself:
Currently, the order of these standalone validations cannot be viewed or changed. This has been noted as feedback for future enhancements.
If you promote one or more PRs while a standalone validation is in progress, those PRs will appear in the queue as normal, but will not start promoting until the validation has completed:
Note: Promotions are prioritised over standalone validations. This means that if there are PRs queued for promotion under Next, those promotions will be processed before any pending validations in the Open section. Once all promotions in the queue have completed, we will then kick off the pending validations. See a complete example of how the ordering works below.
Example of promotions and validations
Consider the following scenario with standalone validations and promotions:
Now: test-field-1 is currently validating (with a "Validation Only" banner).
Next: test-field-2 and test-field-3 are queued for promotion.
Open: test-field-4 and test-field-5 are awaiting validation (indicated by a clock icon).
The sequence of events will be:
test-field-1 finishes validating and returns to the Open section.
test-field-2 is promoted.
test-field-3 is promoted.
test-field-4 begins its standalone validation and moves to the Now section.
test-field-4 finishes validating and returns to the Open section.
test-field-5 begins its standalone validation and moves to the Now section.
test-field-5 finishes validating and returns to the Open section.
Note: In this example, we assume that test-field-4 is validated before test-field-5.
FAQs
When can my PR be added to the queue?
The PR must meet all necessary prerequisites set by your team, such as pre-deployment steps, required reviews and merge conflict resolution.
What if I merge my PR through my Version Control System (VCS)?
If a PR is merged directly through your VCS, the next CI job run will pick up the changes, as it does today. However, we strongly recommend promoting PRs within Gearset Pipelines to ensure the queueing order is followed (this also helps to avoid potential issues with PRs showing on "Recent promotion history" tab in a sequence users aren't expecting).
What should I do if I need to commit additional changes to a PR that is already in the queue?
We strongly recommend removing the PR from the queue before making changes to ensure they are correctly reflected. Once you have removed it, you can follow the guidance in this article. If the PR is edited while still in the queue, the changes will be picked up as long as the PR has not reached the top of the queue. However, removing the PR from the queue first is the safest approach.
How does this work for long-term projects and releases?
Long-term projects and releases result in a single PR, which will behave like any other PR within the queue.
Why are my PRs promoting as normal rather than joining the queue?
The most likely cause is that the queue functionality is not supported. There are two scenarios that could cause this:
Using a Layered Modules pipeline.
Your team has the 'skip validate before merge' flag enabled.