Workflows
This guide covers OpsChain 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
- 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.
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.
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.
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, and all pending, queued, or running steps are transitioned to the cancelled state.
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 state with their original timings. Steps that were actively running when the workflow run ended are restarted from the beginning.
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.
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.
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.
Approval steps are always exempt from skipping — a step with requires_approval_from set will run regardless of any matching pattern.
The same skip_steps feature is available on changes. See skipping steps for more information, including MintModel step matching.
Execution options
By default, OpsChain 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, OpsChain 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 OpsChain'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'
Update the username, password, host, port and project code to reflect your OpsChain server configuration.