Introduction
Understanding organizationsUnderstanding componentsManage organizationsManage componentsManage component Jira integrations
Set up your first organizationUnderstanding users and teamsUnderstanding role-based access controlManage usersManage teamsConfigure role-based access controlRBAC permissions reference
Understanding authentication in CloudBees UnifySet up multifactor authenticationConfigure SAML single sign-onConfigure OIDC authenticationConfigure network security policiesNetwork security reference
Understanding platform configurationUnderstanding environmentsManage properties and secretsManage environmentsTrack environment inventoryConfigure containersSet up preconfigured actionsConfigure notifications
Accessibility policy referenceShared responsibility model referenceSubscription and services agreementSupport policiesSupported browsers and external tools
Introduction
Understanding feature managementUnderstanding Configuration as CodeGet started with feature managementCreate and manage feature flagsConfigure feature flag targetingOrganize feature flagsImplement feature flag governanceConfiguration as Code reference
Understanding flag impressions and activity statusUnderstanding flag healthUnderstanding code referencesReview and clean up feature flagsSet up code references
Understanding Jira integration for feature flagsSet up the Jira integrationLink Jira tickets to feature flags
Understanding multiple SDK keysBuild your first mobile app with feature flagsBuild your first feature-flagged web applicationBuild your first feature-flagged backend serviceInstall client-side SDKsInstall server-side SDKsConfigure multiple SDK keysMobile SDK referenceWeb SDK referenceBackend SDK referenceClient SDK referenceFlag implementation reference
Introduction
Understanding CI workflowsCreate a build workflowCreate and manage workflowsCreate reusable workflowsTest and validate containers in workflowsCheck out source codeTrigger workflows remotelyWorkflow syntax referenceJobs syntax referenceSteps syntax referenceServices syntax reference
Monitor workflow runsView test results in runsView evidence in runsView deployments in runsManage workflow artifactsPublish test resultsPublish evidence itemsGenerate a software bill of materialsManage ServiceNow change requests
Configure workflow credentialsConfigure AWS credentialsConfigure container registry credentialsConfigure Git credentialsIntegrate external secret providers
Understanding GitHub Actions integrationSet up GitHub Actions integrationDisplay GitHub Actions workflows and runsRegister GHA build artifactsPublish GHA deployed artifactsPublish GHA test resultsPublish GHA evidence itemsTrigger CloudBees workflows from GitHub ActionsScan with GitHub Actions
Understanding CloudBees CI and Jenkins® integrationConnect CI and Jenkins controllersMonitor CI and Jenkins buildsRegister CI build artifactsRegister CI deployed artifactsPublish CI test resultsConfigure CI security scanningCI and Jenkins integration reference
Build and publish container imagesUnderstanding external CI/CD integrationsRun external CI/CD jobsExternal CI/CD action reference
Introduction
Understanding release orchestrationManage applicationsCreate deployer workflowsCreate staged workflowsCreate and manage releasesOrchestrate multi-workflow releasesRelease management reference
Understanding artifact managementRegister and track artifactsStore and retrieve artifactsPromote artifactsGenerate a software bill of materialsArtifact management reference
Deploy with HelmDeploy to KubernetesContainer deployment reference
Deploy to AWSAWS deployment reference
Deploy with enterprise platformsExecute remote deployment commandsEnterprise deployment reference
Verify deployments with New RelicDeployment verification reference

Orchestrate multi-workflow releases

3 minute read

Use the cloudbees-io/workflows-dispatch action to trigger multiple workflows from a single workflow step, either in parallel or sequentially. This is useful in release orchestration scenarios where a release stage must coordinate multiple independent deployment workflows across components or environments.

All CloudBees action repositories are listed at CloudBees, Inc. on GitHub.
Before using this action, you must generate a personal access token in CloudBees Unify. All workflows to be dispatched must be manually triggered workflows. Refer to Configure workflow credentials for token configuration guidance.

Configure the dispatch action

Add the cloudbees-io/workflows-dispatch action to a workflow step and point it to a JSON file that lists the workflows to dispatch.

YAML step inputs

The following inputs configure the dispatch action in your workflow YAML:

Table 1. YAML file specifications
Input name Data type Required Description

workflows-dispatch-file

String

Yes

Path to the JSON file containing workflow dispatch requests.

token

String

Yes

Authorization token to authenticate workflow dispatch requests. CloudBees recommends passing the token as a secret reference.

execution-mode

String

No

Whether to dispatch all workflows in parallel or sequentially. Supported values: parallel (default) or serial.

wait-for-completion

Boolean

No

Whether to wait for workflow executions to complete. Defaults to false when execution-mode: parallel is set. When execution-mode: serial is set, is always considered true.

JSON dispatch file inputs

The dispatch file is a JSON array where each entry specifies a workflow to trigger:

Table 2. JSON file specifications
Field Data type Required Description

workflow_file_name

String

Yes

The name of the workflow file to dispatch.

branch_name

String

No

The branch containing the workflow to dispatch. Defaults to the same branch as the caller workflow.

component_id

String

No

The ID of the component containing the manually triggered workflow (located in CloudBees Unify URL after componentId=). Defaults to the component ID of the caller workflow.

inputs

Object

No

Input parameters to pass when dispatching the workflow. Represented as key-value pairs where keys and values are both strings.

ignore_failures

Boolean

No

Whether to ignore workflow trigger or execution failures. Defaults to false. When both execution-mode: parallel and wait-for-completion: false are set, is always considered true.

Understand execution behavior

The combination of execution-mode and wait-for-completion controls how the action handles dispatch and failure:

Table 3. Execution mode and wait-for-completion behavior
When the following inputs are specified: The following results are observed:

execution-mode:

wait-for-completion:

parallel

false

The action triggers all workflows in parallel. Once triggered, the action step passes regardless of any failures. The ignore-failures parameter is always considered false for this scenario.

parallel

true

The action triggers all workflows in parallel and waits for all triggered runs to complete. If all runs are successful, the action step passes. If a dispatched workflow fails and has ignore-failures: true specified, it does not affect the action step result. If a dispatched workflow fails and has ignore-failures: false specified, the action step fails.

serial

true [1]

The action triggers each workflow sequentially: as soon as one run completes, the next is triggered. If all runs are successful, the action step passes. If a dispatched workflow fails and has ignore-failures: true specified, the action continues to trigger the next workflow in the series. If a dispatched workflow fails and has ignore-failures: false specified, the action step fails on first failure and subsequent workflows are not triggered.

[1] The wait-for-completion parameter is always considered true when execution-mode: serial is set.

Usage examples

Dispatch workflows with default settings

The following example uses the default settings (execution-mode: parallel, wait-for-completion: false):

    - name: Dispatch workflows
      uses: cloudbees-io/workflows-dispatch@v1
      with:
        workflows-dispatch-file: dispatch_requests.json
        token: "${{ secrets.TOKEN }}"
▼

The dispatch_requests.json file for the above:

[
  {
    "workflow_file_name": "workflow-1.yaml"
  },
  {
    "workflow_file_name": "workflow-2.yaml"
  }
]
▼

Await completion of all dispatched workflows

The following example executes workflows in parallel and waits for all to complete:

    - name: Dispatch workflows and wait for completion
      uses: cloudbees-io/workflows-dispatch@v1
      with:
        workflows-dispatch-file: dispatch_requests.json
        token: "${{ secrets.TOKEN }}"
        execution-mode: "parallel"
        wait-for-completion: true
▼

The dispatch_requests.json file for the above, including inputs and cross-component dispatch:

[
  {
    "workflow_file_name": "workflow-1.yaml",
    "inputs": {
      "testkey1": "value",
      "testkey2": "50"
    }
  },
  {
    "component_id": "abcdef90-1234-5678-9abc-defab1234567",
    "branch_name": "branch-2",
    "workflow_file_name": "workflow-2.yaml"
  }
]
▼

Dispatch workflows sequentially with selective failure handling

The following example executes workflows sequentially and ignores failures for one but not the other:

    - name: Dispatch workflows sequentially and ignore failures
      uses: cloudbees-io/workflows-dispatch@v1
      with:
        workflows-dispatch-file: dispatch_requests.json
        token: "${{ secrets.TOKEN }}"
        execution-mode: "serial"
▼

The dispatch_requests.json file for the above:

[
  {
    "component_id": "12345678-9abc-de12-a123-456789abcdef",
    "branch_name": "branch-1",
    "workflow_file_name": "workflow-1.yaml",
    "inputs": {
      "testkey1": "value",
      "testkey2": "50"
    },
    "ignore_failures": true
  },
  {
    "component_id": "abcdef34-1234-5678-9abc-def341234567",
    "branch_name": "branch-2",
    "workflow_file_name": "workflow-2.yaml",
    "ignore_failures": false
  }
]
▼

In the above example, workflow-2 is executed regardless of whether workflow-1 has failed. If workflow-2 completes successfully, the action step passes. If workflow-2 fails, the action step fails.

Related pages

Create and manage releases
Release management reference