Skip to main content

Workflows

This guide covers MintPress workflows, running them, and options available to manage their execution. After reading this guide you should understand:

  • what a workflow run is and how it executes
  • how to skip steps when starting or retrying a workflow run
  • how to let a workflow run continue when a step fails
  • configuration options available to control workflow run execution
  • adding and using workflow run metadata

Overview​

A workflow is an ordered series of steps — changes, wait steps, approval steps, and nested workflows — organised into stages. Running a workflow creates a workflow run. Unlike a change, which applies a single action from a Git repository, a workflow orchestrates multiple changes across one or more projects, environments, or assets.

Learning more

For a guided walkthrough of building a workflow, see the workflows tutorial.

For information on the GUI workflow editor and the full step type reference, see the workflows GUI guide.

Workflow run lifecycle​

A workflow run, and the steps that make it up, transition between states as they execute — mirroring the change & step lifecycle.

When a workflow run is created its state is set to initializing while its initial steps are prepared. Once ready it moves to pending. A step remains pending until its prerequisites are complete. If a step fails, any steps still pending in the same stage will be set to aborted, unless the step or its stage ignores the failure or the stage has on_failure or always steps, which still run. When a branching stage or a wait step with choices runs one arm, the steps in its other arms are set to skipped.

When a step starts executing it enters the queued state while waiting for a worker, then running while actively executing. On completion it transitions to success or error, or to warning when it succeeded only because a failure was ignored. A warning is passed up to the step's parents and the workflow run, so a run that ignored a failure, or that ran a change or child workflow run that finished warning, finishes warning itself. warning counts as a successful outcome.

A running workflow run can be cancelled by anyone with permission to execute the workflow — the same permission required to start it. If a workflow run is cancelled, all finalised steps remain in their existing state, steps that are queued or running are set to cancelled, and steps that have not started (pending) are set to aborted. A running stage's on_cancel steps are the only steps that then run. A workflow step that runs a child workflow run or a change is cancelled at once as well. The child is told to cancel, and its own on_cancel steps may still be running after the parent workflow run has finished as cancelled.

Pausing and resuming a workflow run​

A running workflow run can be paused and resumed — see the API reference for the pause/resume endpoints — mirroring pausing and resuming a change: steps already running or queued continue to completion, and pausing only stops the run from admitting further steps until it is resumed. The same pause_state values (none/pausing/paused) and paused_by history are reported, and the same worker pod build avoidance applies if it is paused before it has started.

Retrying workflow runs​

Workflow runs that have failed or been cancelled can be retried. When retrying, completed steps are not rerun — they remain in the success or warning state with their original timings — except steps whose failure was ignored (see continuing when a step fails). Steps that were actively running when the workflow run ended are restarted from the beginning.

A retry keeps the run's property overrides, and they cannot be changed when retrying. A step that failed because of an override value, such as a stage with no arm for it, fails the same way on retry, so start a new run with corrected overrides instead.

A branching stage or wait step keeps the arm it chose in the original run. It chooses again only if reset_on_retry is true for it (the default for a wait step, and false for a stage) and the step that failed is inside it or in one of its siblings. A stage whose on_failure steps ran is retried from its first child, unless it sets retry_from: failed_step.

A change or child workflow run that completed successfully is reused by the retry rather than run again, so it belongs to both the original run and the retry. Its details in the GUI list every workflow run it belongs to — see header information.

Continuing when a step fails​

Set ignore_failure: true on a step to let the workflow run continue when that step fails. Change, workflow and stage steps accept it. Wait and approval steps do not.

steps:
- type: stage
name: Remove old servers
run_as: parallel
ignore_failure: true
children:
- type: change
target: /projects/web/environments/dev/assets/server1
action: destroy
- type: change
target: /projects/web/environments/dev/assets/server2
action: destroy
- type: change
target: /projects/web/environments/dev/assets/load_balancer
action: reconfigure
ignore_failure: true
- type: change
target: /projects/web/environments/dev/assets/load_balancer
action: verify

What happens when a step that ignores failures fails depends on the step type:

  • Change and workflow steps — if the change or child workflow run fails, ends in a system error, or cannot be created, the step is marked warning and the workflow run moves on. The change or child workflow run keeps its own failed status, so you can still open it to see what went wrong. The step's log records that the failure was ignored.
  • Stages — if one of the stage's children fails, the stage is marked warning and the workflow run moves on to the next step after the stage. In a sequential stage, the children that have not started yet are aborted. In a parallel stage, the remaining children run to completion.

On a change step with targets, or a workflow step with a list of property_overrides, each generated step ignores its own failure, so one failed change or child workflow run does not stop the others.

When you retry a workflow run, steps whose failure was ignored are run again, the same as steps that failed.

In the workflow editor and the workflow run views, steps that ignore failures are marked with an icon.

tip

To ignore the failure of an action within a change, rather than a workflow step, see ignoring an action failure.

Skipping steps​

When creating or retrying a workflow run, you can supply a skip_steps array of glob patterns. Any workflow step whose name matches a pattern is automatically skipped at runtime. Patterns match the steps inside arms and choices by their names too; an arm's own name is not matched.

The skip_steps mask is carried forward automatically on retry — previously-skipped steps remain skipped without needing to be resubmitted. The mask can be overridden at retry time.

Unlike a change, a workflow run cannot start partway through. To begin later in a workflow, skip the steps before the one you want.

note

Approval steps are always exempt from skipping — a step with requires_approval_from set will run regardless of any matching pattern.

A plain wait or input step named in skip_steps is skipped, and a pattern that names a stage skips everything inside it. A when condition or arm selection on the way to an approval is still evaluated, even though its stage was skipped, and a change step inside a skipped stage still runs once its approval is given. See skipping steps.

tip

The same skip_steps feature is available on changes. See skipping steps for more information, including MintModel step matching.

Execution options​

By default, MintPress allows only one instance of a given workflow to run at a time. If concurrent execution is appropriate, you can modify the allow parallel runs of the same workflow setting on the project.

Workflow run metadata​

When creating a workflow run, MintPress allows you to associate additional metadata with it. This metadata can then be used:

  • when searching for workflow runs (via the web UI)
  • when reporting on and searching the workflow run history (via the API)

Adding metadata to a workflow run​

On the GUI, you can add metadata to a workflow run by filling in the metadata fields in the run creation form.

Query workflow runs by metadata​

You can query workflow runs by metadata via the search field in the activity page.

When querying workflow runs via the API, you can use MintPress's API filtering feature to limit the response to runs whose metadata matches a specified value, e.g.:

curl -G --user "{{username}}:{{password}}" 'http://<host>/api/projects/{{project_code}}/workflow_runs' --data-urlencode 'filter[metadata_text_cont]=CR921'
note

Update the username, password, host, port and project code to reflect your MintPress server configuration.