Skip to main content

Workflows

A workflow is how you orchestrate a series of steps to be performed as a single unit of work. Workflows let you sequence work across multiple environments and assets, add human checkpoints, and call other workflows - all from a single starting action.

Workflows are versioned and can be collaboratively edited. They also support a templating language so you can refer to multiple environments and assets using MintPress's properties.

Supported step types​

A workflow can contain any of the following step types, grouped into stages whose steps run either sequentially or in parallel:

  • Changes - execute an action against an asset.
  • Wait steps - pause until a user manually continues the step.
  • Approval steps - pause until a user (or member of an LDAP group) approves or rejects the step.
  • Other workflows - call a previously published workflow as a child of this one.

Stages and wait steps can also branch: a stage can run extra steps when its children fail, or run one of several arms depending on the workflow's properties, and a wait step can let a person pick which steps run next. See branching stages and letting a person choose what runs next.

See the step types reference below for the full set of properties each step type accepts.

warning

Take care when nesting workflows - it is possible to create a workflow that indirectly calls itself and therefore never ends.

Workflow list​

The first tab on this page lists all the workflows of a selected project.

Workflow list

Each row includes:

ColumnDescription
NameDisplays the name of each workflow.
VersionDisplays the latest version of the workflow, and whether it is a draft version or a published one.
CodeShows a unique identifier for the workflow.
DescriptionProvides a short summary or purpose of the workflow.
Created byThe user who created the workflow.
Created atTimestamp for when the workflow was created.
Updated atTimestamp for when the workflow was last updated.
ArchivedWhether the workflow is archived or active.
Buttons & linksFunction
Project dropdownSelect the project to filter the workflows by. The project is part of the page's address, so the list can be bookmarked or shared.
Search barFilter the contents of the table based on these criteria.
ColumnsHide or display columns in the table.

Clicking on a specific workflow will redirect you to its details page.

Workflow editor​

The workflow editor page allows you to create and edit workflows. It features a tab system, allowing you to switch between different workflows while editing them. The editor is composed of four main panes: the workflow details and actions at the top, the YAML editor, the tree view preview and the logs pane. Each is described below.

Workflow editor

To create a new workflow, click the New workflow button, or choose Workflow from New in the top bar on any screen, which picks the project you are viewing for it to be saved to. Any workflows you already have open are available as tabs on this page. Each tab, including an unsaved draft, has its own address, so the browser's back and forward buttons move between them. Edit on a workflow anywhere in the GUI opens it here. As you edit the YAML definition, the tree view on the right updates to preview how the workflow will run.

Workflow details and actions​

The top of the editor shows the workflow's details and the actions available for it.

When creating a workflow that has not been saved yet, this area displays Local workflow, indicating the workflow exists only in your browser and is not yet available to other users. A Save button lets you persist it for the first time, prompting you for the workflow's project, name and code.

Once a workflow has been saved, this area shows its project, name, current version and whether that version is a draft or published, along with the following actions:

ButtonFunction
RunAllows you to open the run workflow dialog if the currently loaded workflow in the editor is published.
Discard changesDiscards the changes made to the workflow.
Save changes dropdownAllows you to save the changes to the current version or create a new version with these changes.
ValidateValidates the workflow - will show an error in the logs pane if it does not conform to the expected workflow schema.
PublishPublishes the current version of the workflow. If the current version has not been validated, it will be validated first. If validation fails, the workflow will not be published.
Local drafts

Until you save a workflow, its definition is kept only in your browser's local storage. If you clear your local storage before saving, an unsaved draft may be lost.

Editor pane​

The editor pane holds the YAML definition of the workflow. When creating a new workflow, it is pre-populated with a template definition to get you started, and it offers autocompletion for step properties, target paths and action names as you type.

At the bottom of the editor pane, the Quick add buttons insert ready-made step snippets so you don't have to write them from scratch:

Quick addInserts
ActionA change step. Fill in the target path and action name.
WorkflowA child workflow step. Fill in the target project, workflow and version.
WaitA wait step.
ApprovalAn approval step. Fill in the name and the users/LDAP groups that can approve it.
SequentialA sequential stage that you can add child steps to.
ParallelA parallel stage that you can add child steps to.

See the step types reference for the full list of properties each step type accepts.

Tree view​

The tree view on the right side of the editor renders a live preview of the workflow as you edit it, showing the stages and steps in the order they will run and how they are nested. This is the same view used to follow a workflow run, so it is a quick way to confirm the structure matches your intent before validating or publishing. When the workflow uses variables, the preview reflects how the workflow resolves with the values you provide. A branching stage shows each of its arms, so you can check every path the workflow can take.

Logs pane​

The logs pane records events for the current workflow - when it was created, modified, validated and published. When validation fails, the validation error is shown here, pointing you at the part of the definition that needs fixing.

Using variables in the workflow​

You can use properties to dynamically set targets, actions and names based on properties values. In workflows, variables are represented by double curly braces, e.g. {{property_name}}. When clicking on the Validate button, the Validate properties overrides dialog will show you the identified variables and allow you to validate the workflow with values specified by you.

When running the workflow, the properties overrides will be used to resolve the variables. If the provided overrides are invalid or not provided, an error message will be shown in the Run workflow dialog.

When values are resolved

{{...}} variables are substituted once, when the run is created. A when condition is checked later, as its step or stage starts, against the properties as they are at that moment.

Read more about properties in the properties concept page, and about how a run's overrides resolve these variables in workflow run property overrides.

Step types reference​

Every entry in a workflow's steps list (and in a stage's children, on_failure, on_success, always and on_cancel lists, an arm's children and a wait step's choices) is a step. The type property determines the kind of step. When type is omitted, MintPress infers it from the other properties present:

  • a step with action is a change step
  • a step with target but no action is a workflow step
  • a step with requires_approval_from is an approval step
  • any other step is a stage.

A wait step has no property that identifies it, so it must always set type: wait.

The sections below list each step type and the properties it accepts. A property marked as required must be present for the step to validate.

Change step​

Executes an action against a single asset.

PropertyRequiredDescription
targetyesThe full MintPress path to the asset to run the action on, e.g. /projects/hello_world/environments/dev/assets/managed_server.
actionyesThe action to run on the target.
template_versionnoThe asset template version to source the action from. Defaults to the target's current template version at runtime.
namenoA human-readable name for the step, shown in the editor and run views.
start_timenoA scheduled start time in ISO8601 format (e.g 2026-06-02T10:00:00Z). The step waits until this time before running.
property_overridesnoProperties to override or add to the target's configured properties for this run.
ignore_failurenoWhen true, the workflow continues if the change fails. See continuing when a step fails.
whennoA condition on the target's properties. When it does not match, the step is skipped. See running a step only when a condition holds.

Change step with multiple targets​

Runs the same action against several targets. Replace target with targets and, optionally, template_version with template_versions.

PropertyRequiredDescription
targetsyesA list of MintPress paths to run the action on.
actionyesThe action to run on each target.
template_versionsnoA list of template versions, in the same order as targets.
run_asnosequential (default) or parallel - whether to run the action on the targets one at a time or all at once.
namenoA human-readable name for the step.
start_timenoA scheduled start time in ISO8601 format.
property_overridesnoProperties to override or add to the targets' configured properties for this run.
ignore_failurenoWhen true, the workflow continues if a target's change fails. See continuing when a step fails.
on_failure, on_success, always, on_cancel, recover, retry_from, abort_on_reject, abort_on_cancelnoSteps to run depending on how the changes finished, as on a stage. See rolling back a multiple target change. Cannot be combined with ignore_failure or when; put the step in a stage that has them instead.

Wait step​

Pauses the workflow until any user with access to the workflow manually continues it.

PropertyRequiredDescription
typeyeswait.
namenoA human-readable name for the step. Defaults to Wait.
reset_on_retrynoWhen true, the step needs to be continued again if the workflow is retried. Defaults to true. In an action, a plain wait step defaults to false.
choicesnoA list of choices, each with a name, an optional label and its children. The user picks one when continuing the step. See letting a person choose what runs next.
defaultnoThe choice used when the step is continued without one: automatically, in bulk, or through the API or CLI without a choice.
whennoA condition on the workflow's project properties, merged with the run's property overrides. When it does not match, the step is skipped.

Letting a person choose what runs next​

Give a wait or approval step choices to have the person continuing it pick which steps run next. Each choice has a name, an optional label shown on its button, and its children, which can be empty:

- type: wait
name: Promote to DR?
requires_approval_from:
ldap_groups: [ops-leads]
choices:
- name: promote
label: Promote DR now
children:
- type: change
name: Promote DR
target: /projects/weblogic/environments/dr/assets/app_domain
action: promote
- name: skip
children: []
default: skip

When the run reaches the step, the step shows a button for each choice, in the order written, in place of Continue or Approve. A choice without a label shows its name with underscores replaced by spaces and a capital first letter, such as Skip. Picking one runs that choice's steps, and the steps in the other choices are set to skipped. On an approval step, only the approvers can choose, and they can still reject the step instead.

A step with a default choice uses it when it is continued without a choice: by Continue selected or Approve selected in manage activity, or through the API or CLI without one. A choices step without a default is left waiting by bulk actions, and a request without a choice is rejected with the list of choices. See choosing without the step's buttons for the API and CLI.

When the run is retried, the person is asked to choose again if the step that failed is inside the step or in one of its siblings, unless the step sets reset_on_retry: false.

Approval step​

An approval step is a wait step that can only be continued by specified users or LDAP group members, who have to approve or reject it. Adding requires_approval_from to a wait step turns it into an approval step.

PropertyRequiredDescription
typenowait. Can be omitted, as requires_approval_from identifies an approval step.
requires_approval_fromyesAn object naming who can approve the step. Must contain user_names and/or ldap_groups.
requires_approval_from.user_names–A list of usernames allowed to approve the step. Must contain at least one username when defined.
requires_approval_from.ldap_groups–A list of LDAP groups whose members can approve the step. Must contain at least one LDAP group when defined.
namenoA human-readable name for the step. Defaults to Approval.
reset_on_retrynoWhen true, the step needs to be approved again if the workflow is retried. Defaults to true. In an action, a plain approval step defaults to false.
choicesnoA list of choices, each with a name, an optional label and its children. The approver picks one when approving the step. See letting a person choose what runs next.
defaultnoThe choice used when the step is approved without one.
whennoA condition on the workflow's project properties, merged with the run's property overrides. When it does not match, the step is skipped.

Workflow step​

Calls a previously published workflow as a child of the current one.

PropertyRequiredDescription
typenoworkflow. Can be omitted when the step has no action.
targetyesThe OpsChain path of the workflow to run, e.g. /projects/hello_world/workflows/backup-environment.
versionnoThe version of the child workflow to run. If omitted, the latest published version is used.
namenoA human-readable name for the step.
start_timenoA scheduled start time in ISO8601 format.
property_overridesnoProperty overrides to supply to the child workflow.
ignore_failurenoWhen true, the workflow continues if the child workflow run fails. See continuing when a step fails.
whennoA condition on the child workflow's properties. When it does not match, the step is skipped.

By providing the same property in the property_overrides key multiple times, the child workflow will be called once for each value. You can then use the run_as property to control the execution strategy of these child workflow steps.

warning

Take care when nesting workflows - it is possible to create a workflow that indirectly calls itself and therefore never ends.

Stage​

Groups a set of child steps to run sequentially or in parallel. Stages can be nested inside other stages to build more complex structures.

PropertyRequiredDescription
run_assee notesequential to run children one at a time, or parallel to run them all at once. Required unless arms is set.
nameyesA human-readable name for the stage.
childrensee noteThe list of steps nested within the stage. Required unless arms is set.
on_failurenoSteps to run if any of the stage's children fails. See running steps when a stage fails.
on_successnoSteps to run if all of the stage's children succeed.
alwaysnoSteps to run last, whether the stage's children succeeded or failed.
on_cancelnoSteps to run if the run is cancelled while the stage is running. on_failure and always do not run on a cancel.
recovernoWhen true, the stage ends in warning if its on_failure steps succeed, so the run carries on. Defaults to false.
abort_on_rejectnoWhen true, a rejected approval among the stage's children stops the stage with no on_failure or always steps, instead of failing it. See when an approval is rejected or a step is cancelled.
abort_on_cancelnoWhen true, a step among the stage's children that is cancelled on its own stops the stage with no on_failure or always steps, instead of failing it.
retry_fromnoWhere a retry restarts a stage whose on_failure steps ran: start (default) or failed_step.
armsnoA list of arms, each with a name, a when condition, its own children, which can be empty, and an optional run_as (default sequential). The stage runs the first arm that matches. A stage with arms must set type: stage. See choosing an arm by property.
defaultnoThe name of the arm to run when no arm's when matches.
whennoA condition on the workflow's project properties, merged with the run's property overrides. When it does not match, the whole stage is skipped, including its arms and handler steps, all shown as not taken, and the run carries on with the next step. When it matches, the stage chooses its arm or runs its handlers as usual.
reset_on_retrynoWhen true, a retried run checks the stage's when again and chooses an arm again, if the step that failed is inside the stage or in one of its siblings. Defaults to false.
ignore_failurenoWhen true, the workflow continues if one of the stage's children fails. See continuing when a step fails.
Execution strategy conflicts

The steps generated by the multiple target change and multiple child workflow (via property overrides) steps will follow the execution strategy defined in the step themselves. For example, if a step is defined with run_as: parallel, all of its children will run in parallel, regardless of the execution strategy defined in the stage.

Branching stages​

A few terms used here:

  • A stage groups steps under a name, and its children are the stage's main steps.
  • A handler is a list of steps that runs depending on how the main steps finished: on_failure, on_success, always or on_cancel.
  • An arm is a named list of steps that runs only in some cases: a handler, one of a stage's arms, or one of a wait step's choices.
  • A step is skipped on request when you skip it with skip_steps, and not taken when it belongs to an arm that did not run. The step tree shows which.

A stage can branch in two ways. With on_failure, on_success, always and on_cancel, it runs extra steps depending on how its children finished. With arms, it runs one of several arms and none of the others. Arms that do not run are set to skipped, and the run's step tree shows why.

Workflow tree preview with a rollback, a conditional step, a regional choice and a DR decision

These are the same branches an action can declare in actions.rb, and they finish the same way. Two things differ: a plain wait or approval step asks again on retry by default in a workflow but not in an action, and a when condition compares values differently from an action's run_if. See branching, and how a group with handlers finishes for what each arm does when something fails or the run is cancelled.

When a workflow version is published, MintPress also checks that:

  • every arm of a stage, and every choice of a wait step, has a name, and every stage arm has a when
  • the names of a stage's arms, or of a wait step's choices, do not differ only in case
  • a step name is not used in more than one arm of the same stage, or more than one choice of the same wait step. It can be repeated within one arm
  • a when condition's target: exists and you can read it. In a workflow that uses {{ }} variables, this is checked when a run is created instead
  • a change step with a single target has no on_failure, on_success, always or on_cancel steps. Put it in a stage that has them instead

Running steps when a stage fails​

- type: stage
name: Patch prod with rollback
run_as: sequential
children:
- type: change
name: Patch app domain
target: /projects/weblogic/environments/prod/assets/app_domain
action: patch_weblogic
on_failure:
- type: workflow
name: Restore prod
target: /projects/weblogic/workflows/restore-prod
always:
- type: change
name: Notify release channel
target: /projects/weblogic/environments/prod/assets/app_domain
action: notify

If a step in children fails, the on_failure steps run, then the always steps. The stage then ends in error and the run stops, even when the on_failure steps succeeded. Set recover: true for the run to carry on once they have. The stage, and the run, then finish warning rather than success, so a notification subscription or event filter on success does not match a run that recovered. A stage with recover: true whose on_failure steps were all skipped recovered nothing, so it still ends in error, and its on_failure arm shows Recovered nothing: none of its steps ran. A stage with handlers cannot set ignore_failure; use recover: true instead.

When an approval is rejected or a step is cancelled​

note

By default, a rejected approval among a stage's children, or one of its steps cancelled on its own, makes the stage fail, so its on_failure and always steps run. Set abort_on_reject: true or abort_on_cancel: true on the stage to stop it instead, with no handler steps. Cancelling the whole workflow run is different: only on_cancel steps run.

A rejected approval counts anywhere inside the stage's children, including in a plain stage nested in them, and so does a step cancelled on its own inside such a stage. A nested stage with on_failure, on_success or always steps of its own, or with ignore_failure, decides its own outcome. abort_on_cancel reacts only to the stage's own direct children that were cancelled. A rejection or cancellation inside an on_failure, on_success or always list fails that list like any other failure. A failure in on_success or always stops the remaining handlers, which are set to aborted and show Not run: on_success failed, while a failure in on_failure still lets always run. A stage stopped by its own flag fails its parent, so the run does not finish success.

Cleaning up after a cancel​

Cancelling a workflow run stops it. A stage that was running when the run was cancelled runs its on_cancel steps, and so do the stages that contain it, once the steps that were running have stopped. Their actions are stopped before the on_cancel steps start. on_failure and always do not run on a cancel, and cancelling the run again stops the on_cancel steps too. The stage then ends in cancelled.

While the on_cancel steps run, the run's status in the GUI reads Cancelling – cleaning up, and its cancel_requested attribute in the API is true.

Cancelling a paused run does not wait for it to be resumed: the on_cancel steps run straight away. The run then ends as cancelled, still flagged as paused.

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.

Rolling back a multiple target change​

A change step with multiple targets takes the same keys directly, without a stage around it:

- type: change
name: Patch the app tier
targets:
- /projects/weblogic/environments/prod/assets/app_domain
- /projects/weblogic/environments/prod/assets/ohs
action: apply_patches
run_as: parallel
on_failure:
- type: change
name: Remove the patches
targets:
- /projects/weblogic/environments/prod/assets/app_domain
- /projects/weblogic/environments/prod/assets/ohs
action: uninstall_patches
run_as: parallel
always:
- type: change
name: Notify release channel
target: /projects/weblogic/environments/prod/assets/app_domain
action: notify

If the patch fails on any target, the patches are removed from every target. A child workflow step with a list of property_overrides takes the same keys.

Choosing an arm by property​

- type: stage
name: Region rollout
arms:
- name: apac
when: { property: region, in: [au, nz] }
children:
- type: workflow
name: APAC rollout
target: /projects/weblogic/workflows/apac-rollout
- name: eu
when: { property: region, equals: eu }
children:
- type: workflow
name: EU rollout
target: /projects/weblogic/workflows/eu-rollout
default: apac

When the run reaches the stage, MintPress checks each arm's when from the top and runs the first that matches, or the default arm if none does. Without a default, a stage where no arm matches fails with an error naming the property and its value, shown on the stage in the step tree.

An arm's when is checked against the project's properties merged with the run's property overrides. A change that sets a project property earlier in the run can therefore steer a later stage.

Running a step only when a condition holds​

Give a change or child workflow step a when to run it only when its target's properties match:

- type: change
name: Migrate search index
target: /projects/weblogic/environments/prod/assets/search
action: migrate_index
when: { property: index_migrated, not_equals: true }

The condition is checked against the step's target, with the step's own property_overrides applied, as the step starts. When it does not match, the step is set to skipped and shows Not taken: index_migrated is true. To run a step only once, have its action set a property on its asset when it finishes, here index_migrated, and test that property in when. To let a run override that, set the property in the step's property_overrides from a workflow variable.

Conditions​

A when names a property by its dotted path and one test:

ConditionMatches when
{ property: <path>, equals: x }The property equals x.
{ property: <path>, not_equals: x }The property does not equal x, or is not set.
{ property: <path>, in: [x, y] }The property equals one of the listed values.
{ property: <path>, not_in: [x, y] }The property equals none of the listed values, or is not set.
{ property: <path>, exists: true }The property is set. Use false to match when it is not set.
  • <path> uses the same dot notation as workflow variables, for example region.name.
  • A property that is not set never matches equals or in; it is not an error.
  • Values are compared with their types as written. Numbers compare by value, so 1 matches 1.0, but a number never matches a string.
  • Add target: to read another project, environment or asset's properties, for example when: { target: /projects/weblogic/environments/prod, property: region, equals: eu }. A condition with target: reads that node's own properties, without the run's property overrides or the step's property_overrides.
  • A when is accepted on every kind of step (change, workflow, wait, approval and stage) and on each arm of a stage. A change or workflow step reads its target's properties, with its own property_overrides applied. A wait, approval or stage step, and each arm, reads the project's properties merged with the run's property overrides. To read another node instead, add target:.
  • A condition is checked as its step or stage starts, and again on a retry when the step's reset_on_retry is true, which is the default for wait and approval steps but not for stages. A {{...}} variable inside a condition is substituted when the run is created, so equals: '{{target_region}}' compares the live property with the run's override.
note

when: compares values with their YAML types. Numbers compare by value, so 1 matches 1.0, but a number never matches a string: equals: 1 does not match a property whose value is "1". Quote the value in when: if the property holds text.

when: { property: replicas, equals: 1 } # replicas: 1 or 1.0 → matches; replicas: "1" → no match
when: { property: replicas, equals: '1' } # replicas: "1" → matches; replicas: 1 → no match

Retrying a run with branches​

A retried run keeps the arm each stage chose, unless the stage sets reset_on_retry: true and a step that failed is inside the stage or in one of its siblings. Wait steps with choices default to asking again. Only a failure among the stage's own children counts; a failure in an on_success or always list does not. A stage whose on_failure steps ran is retried from its first child, which reruns children that succeeded, unless it sets retry_from: failed_step. A stage with recover: true that recovered is treated as done, and a retry for a later failure does not run it or its on_failure steps again. When a stage that sets reset_on_retry: true chooses a different arm on retry, the new arm runs, and an arm that succeeded in the original run keeps its status, times and the change or child workflow run it ran. A retry cannot change the run's property overrides, so a stage that failed because of an override value needs a new run.

Skipping steps in branches​

skip_steps patterns match steps inside arms and choices by their names, and a pattern that names a stage covers everything inside it. An arm's own name is not matched. A skipped region never skips an approval step: the run still reaches every approval in it.

In a skipped regionWhat happens
Change, workflow and plain wait stepsSkipped, whether named in skip_steps directly or inside a skipped stage
An approval stepStill asks for approval
A when or arm selection on the way to an approvalStill evaluated, which runs that step's own action
A wait step with choices whose choice leads to an approvalStill asks for the choice
An approval in an arm or condition that is not takenSkipped as not taken
on_success and always of a stage entered only to reach an approvalSkipped, unless they hold an approval, and not listed as arms taken

Steps that did not run show as skipped, as requested; a stage whose steps ran shows its real outcome.