Use staged workflows to organize complex release activities into structured stages, each representing a deployment or transition across environments such as staging, production, or QA. Refer to Understanding release orchestration to understand how staged workflows fit into the release model.
Unlike standard workflows, staged workflows enable:
-
Organized release phases: Break the release into distinct steps such as build, test, and deploy.
-
End-to-end visibility: Manage work across environments using a consistent flow.
-
Better debugging: Understand which stage failed and why, faster.
Use standard workflows for simple CI/CD tasks. Use staged workflows when your releases span multiple steps, teams, or environments.
| Before creating a staged workflow, ensure your application has an integrated source repository. If you want to call a deployer workflow from your staged workflow, the application must include one. If no deployer exists, CloudBees Unify can generate one automatically during staged workflow creation. |
Create a staged workflow
To create a new staged workflow:
-
Select Applications, and select your application.
-
Select .
-
Select Create staged workflow.
If no deployer exists for your application, you are prompted to create one using the assisted creation option. Refer to Create deployer workflows for details.
If a deployer is available, the initial staged workflow includes a deployer job in each environment stage.
Use assisted deployer workflow creation
CloudBees Unify provides an assisted creation experience to generate a deployer workflow if one does not exist.
Assisted creation checks for a deployer.yaml workflow file on the default branch that includes an on.workflow_call trigger with the required parameters manifest and environment, both of type string.
If a deployer is not present, you are prompted to make a choice:
-
Select Use the assisted deployer to generate a deployer automatically based on your current application components.
-
Select No, thanks to proceed without a deployer.
Configure stages in the Workflow composer
Staged workflows render visually in the Workflow composer as stages (
), which you can configure.
Use the composer to:
-
Rename a stage: Select
, then select Edit. -
Add a stage: Hover between stages or over lines and select +.
-
Delete a stage: Select
, and then select Delete.
| Each staged workflow must include at least one trigger, one stage, and one job. |
Add and manage triggers
All staged workflows begin with a manual trigger. You can add push-based, pull request-based, and scheduled triggers.
To add a trigger:
-
In the composer, select Add trigger.
-
Choose a Type and fill in the fields:
-
Push: Select branches and tags.
-
Pull request: Select base branches.
-
Schedule: Provide a CRON expression.
-
-
Select Save, and then commit your changes.
For guidance on available triggers, refer to Create and manage workflows.
Add and manage jobs
Each stage contains jobs. You can add standard or reusable workflow jobs.
To add a job to a stage:
-
In the composer, find the stage you want to update.
-
Select Add job.
-
Choose a Job type:
-
Standard job: Basic CI/CD logic.
-
Reusable workflow call: Points to another workflow, such as
deploy.yaml.
-
-
Fill out the required configuration.
-
Select Save, and then commit the updates.
Save a staged workflow
To save a workflow in CloudBees Unify, commit the YAML file to your repository:
-
Select Commit.
-
Enter a Commit message.
-
(Optional) Select a different branch or initiate a pull request.
-
Select Commit again to confirm.
Once saved, the staged workflow appears in the Workflows list for your application.
Use the Workflow composer
The Workflow composer provides a visual interface for configuring stages, jobs, approvals, environment variables, and more.
Use the composer to:
-
Edit workflow metadata, such as the name and environment variables.
-
Commit workflow updates.
-
Add or delete triggers, jobs, and stages.
-
Collapse or expand stages visually.
-
Insert approval steps.
-
Manage execution order between jobs.
Run a staged workflow
To manually run a staged workflow:
-
Navigate to Applications, select your application, and open the Workflows tab.
-
Select the name of the staged workflow.
-
Select the Branch to run.
-
Select Run.
The primary intended use of staged workflows is within a release.
Refer to Create and manage releases.
A staged workflow can be run as a standalone workflow, but it requires specific input parameters.
By default, a staged workflow is configured to run as a reusable workflow and expects a manifest input parameter containing valid JSON, usually provided by a release manifest.
You can also run staged workflows using configured triggers. Executions are shown in run details.
Update a staged workflow
To make changes to a staged workflow:
-
From , select the staged workflow you want to edit.
-
Select
to open the composer. -
Modify any settings, jobs, triggers, or stages as needed.
-
Select Commit to save and apply changes.