Requeuing Stages

This feature is available from version 1.9.2

Sometimes a build stage may fail due to external influences - it could be that a file server was offline, network connectivity was down, or a file was locked for access. If it has taken several long stages to get to this point, then having to run the whole build again from the start can be a pain.

Providing the last stage of a completed build has one of the outcomes configured on the Enable Requeue options for that stage, and no parts of the server workspace have been removed by the cleanup process, then a Requeue Stage button will be shown after the last stage in the Stages list on the Build page.

Configuring Enable Requeue options

You can control when a stage can be requeued by checking the Enable Requeue options in the Stage Options dialog. These options allow you to specify whether a stage can be requeued:

After failure - The stage can be requeued if it fails, stops, or errors
After success - The stage can be requeued even if it completes successfully
After warnings - The stage can be requeued if it completes with warnings

This gives you flexibility in deciding which stages can be rerun and under what circumstances. By default, stages can be requeued after failure and after warnings.

Requeuing a stage

Clicking on the Requeue Stage button will open a confirmation dialog before restarting the build and adding the stage to the queue.

Any configuration conditions will be skipped, but all configuration and stage shared resource locks will be acquired before the stage is executed.

A new Stage, with the suffix "(rerun)" added to its name, will be added to all Stages lists and in the build log, to represent the requeued stage.

Once the new stage is complete, it can be requeued again and again.

If the new Stage is successful, the build will continue on to the next stage as usual.

Updating stage variables

If the configuration has variables, you can optionally update these variables before requeuing the stage. Simply check the "Update stage variables" checkbox in the confirmation dialog, and you'll be able to edit the variable values on the Variables tab before the stage is requeued.

Requeueing a stage with changes

Sometimes a stage will fail due to a small typo or incorrect field value. What if you could edit the stage and then rerun it?

When you requeue a stage, if any changes have been made to the configuration since the stage was last run, you will be given the option to requeue the latest version of the stage. The latest stage actions will then be added to the queue.

Server workspace

For a stage to be requeued, the server workspace needs to be intact. If any of the workspace files have been removed due to the cleanup settings, then the Requeue Stage button will not be available. Ensure that you adjust the cleanup rules for any configurations for which you may need to requeue stages.

Note that stages are requeued using the server workspace as it is when the build completes. It's up to you to ensure that any agent to server workspace rules do not overwrite files that will be needed when rerunning a stage.

If any other changes were made to the server workspace during the stage run, the requeue confirmation dialog will show a warning message indicating which top-level folders were added, removed or modified, and noting that the requeued stage may be affected by these changes. You will however still be able to continue with the build.