Create and manage workflows

Create, configure, and manage CI workflows using CloudBees Unify’s workflow management features to orchestrate build, test, and deployment activities. Before you begin, ensure you have workflow creation permissions within your component or application.

For conceptual background on workflow architecture and platform integration, refer to Understanding CI workflows.

To access a list of workflows for an application or component:

Use the to select an organization.
Select Applications or Components from the left menu.
Select the application or component name to view the details.
Select the Workflows tab. A list of workflow runs displays.

Create workflows

Use these procedures to create standard or staged workflows for your CI automation needs.

Create standard workflows

Standard workflows handle CI activities like building, testing, and deploying code changes with automatic platform integration.

To create a standard workflow:

Navigate to the workflows list for an application or component.
Select Create standard workflow from the menu.
Use the Workflow composer visual tool, code editor, or both to configure your workflow.

Updates made with the visual tool or the code editor are automatically displayed in both views.

Create staged workflows

Staged workflows coordinate release management activities that span multiple components or require approval gates.

To create a staged workflow:

Navigate to the workflows list for an application or component.
Select Create staged workflow from the menu.
Use the Workflow composer to configure stages and jobs.

Configure workflow components

Configure the core components that define workflow behavior: settings, triggers, jobs, and steps.

Configure workflow settings

To modify basic workflow settings:

In the Workflow composer, select Settings to modify workflow name and env key/value pairs.
Switch the repository branch by selecting the branch name.
Access the Git repository linked to the workflow by selecting the repository name link.

Configure workflow triggers

Configure triggers to define when your workflow runs automatically or manually.

Manual triggers (workflow_dispatch)

Manual triggers allow users with proper permissions to start workflow runs with customizable input parameters.

Only users with administrative permissions can trigger a workflow to run manually.

To configure a manual trigger:

Select Trigger or drag Trigger to the trigger area of the visual composer.
Ensure Manual is the selected Type option.
Create up to 10 input parameters:
1. Select + add parameter.
2. Select an input parameter type from the menu options:
  - String: Allows users to input text-based values for controlling behavior or passing data.
  - Number: Accepts numerical inputs for specifying integer or floating-point values.
  - Boolean: Accepts binary values (true or false) for toggling features or controlling conditional logic.
  - Choice: Allows users to select from a predefined list of options.
3. Enter a name for the parameter.
4. Complete applicable fields:
  - Enter a description for the parameter.
  - Enter a default parameter value.
  - Make the parameter value required by selecting Required.
Change parameter order by selecting and dragging to the new location.
Select Save to keep changes or Cancel to discard.

Avoid using sensitive data like access tokens, encryption keys, secrets, passwords, or personally identifiable information as manual trigger parameters.

Push or pull request triggers

Configure workflows to start automatically on code pushes or pull requests.

To configure a push or pull request trigger:

Select Trigger or drag Trigger to the trigger area of the visual composer.
Ensure Pull request or Push is the selected Type option.
Choose one or more branches in the Branches field by:
- Entering ** to select all branches.
- Selecting an existing branch.
- Defining a branch pattern name.
For push triggers, choose one or more git tags in the Tags field by:
- Defining tag pattern names (recommended), for example "v*".
- Entering a specific tag name, for example "v1.0".
Remove a branch or tag by selecting next to the item.
Select Save to keep changes or Cancel to discard.

Schedule triggers

Use schedule triggers to start workflow runs according to configured cron schedules.

Cron expressions are configured in the UTC timezone. Scheduled triggers execute only on the default branch of the repository.

To configure a schedule trigger:

Select Trigger or drag Trigger to the trigger area of the visual composer.
Ensure Schedule is the selected Type option.
Enter schedules in cron format.
Create additional schedules by selecting + new schedule.
Remove a schedule by selecting next to the schedule.
Select Save to keep changes or Cancel to discard.

Configure jobs

Configure standard jobs

Standard jobs execute build, test, and deployment steps with automatic integration to platform services.

To configure a standard job:

Create a new job by selecting Job and dragging it to the job area of the visual composer.
Enter a name for the job.
Specify job dependencies by selecting Add needs to indicate jobs that must complete successfully before this job runs.
Specify a job run environment by selecting from the Environment options.
Configure job outputs by selecting Add output to specify key-value pairs.

Configure job steps

To manage job steps:

Create a new step by selecting the Add step link.
Complete step configuration fields:
- Enter a name for the step.
- Locate and select a preconfigured action or container from the Uses field options, or select Select from catalog to search the catalog.
- Select a Kind option to use step data for analytics calculations:
  - Select Deploy to use DORA metrics.
  - Select Build to use software delivery activity metrics.
  - Select Scan to use security insights.
  - Select Test to use test insights.
Modify existing steps by selecting next to a step and choosing Edit.
Change step order by selecting and dragging to a new location.
Delete steps by selecting and choosing Delete.

If the Kind option is inappropriate for the step, the data is not collected.

Configure services (Beta feature)

Services is a Beta feature.

To add services to your job:

Select the Add service link.
Complete service configuration fields:
- Enter a name for the service.
- Enter the docker image name or tag.
- Specify the service environment by selecting from the Add environment options.
- Configure argument values that override the values in the CMD Dockerfile.
Modify existing services by selecting next to a service and choosing Edit.

Configure stages

To manage stages in a staged workflow:

Add a new stage by selecting a connecting line to insert a new stage at that point in the workflow sequence.
Select to create the new stage at the selected position.
Modify an existing stage by selecting next to a stage and choosing Edit.
Reorder stages by dragging and dropping to a new location in the workflow sequence.

Job dependencies are updated automatically when a stage is moved to ensure proper job execution order. Review and adjust job needs as necessary after reordering stages before committing changes.

Configure manual approval jobs

Manual approval jobs insert workflow approval steps where approvers receive email notifications. Custom jobs are pre-configured job templates that execute within workflows using the delegates field.

The Approver role (predefined) is used for workflow approvals. Users assigned to this role can approve workflow steps unless specific approvers are defined in the job itself. Workflow approvers do not apply to feature flag changes.

To configure a manual approval job:

Create a new approval job by selecting Approval and dragging it to the job area of the visual composer.
Enter a name for the approval job.
Review or modify the timeout-minutes default value of 4320 minutes (the time approvers have to respond).
Specify job dependencies by selecting Add needs to indicate jobs that must complete before the approval runs.
Select approver names in the Approvers field (both user IDs and email addresses are supported):
- If approvers are specified, only listed approvers receive email notifications and can participate in the approval process.
- If approvers are not specified, only the workflow initiator receives email notifications, but all eligible users can participate.
Enter instructive text for approvers (visible in email notifications and run details).
Optionally select Disallow workflow initiator from approving to prevent the person who starts the workflow from approving it.

Configure approval input parameters

To manage approval input parameters:

Create new parameters by selecting the Add input link.
Configure parameter values with type, default values, and descriptions.
Change parameter order by selecting and dragging to a new location.
Remove parameters by selecting .
Modify existing parameters by selecting next to the parameter.

Use needs along with outputs context to access parameter input values. To return all parameter input values in JSON format, use ${{needs.<approvalJobName>.outputs.approvalInputValues}}. To return a specific parameter value, use ${{ fromJSON(needs.<approvalJobName>.outputs.approvalInputValues).<parameterName> }}.

Manual approval YAML reference

When working directly with YAML, manual approval jobs use the delegates field to reference the CloudBees manual approval custom job.

Required inputs

Table 1. Manual approval inputs
Input name	Data type	Required?	Description
`delegates`	String	Yes	The path to the manual approval custom job YAML file. Use: `cloudbees-io/manual-approval/custom-job.yml@v1`
`instructions`	String	Yes	Instructional text for approvers that appears in email notifications and on the workflow run details page.

Optional inputs

Table 2. Optional manual approval inputs
Input name	Data type	Description
`approvers`	String	Comma-separated list of user IDs or email addresses. If not specified, approval eligibility defaults to users assigned to the Approver role.
`approvalInputs`	String, Boolean, Choice, Number	Input parameters for workflow approvers. Valid types: `string`, `number`, `boolean`, `choice`.
`disallowLaunchByUser`	Boolean	When set to `true`, prevents the workflow initiator from participating in the approval. Default: `false`
`timeout-minutes`	Integer	Time approvers have to respond to the approval request. Default: `4320` minutes (three days)

YAML usage example

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Workflow with manual approval
on:
  workflow_dispatch:
jobs:
  build-approval:
    with:
      approvers: "user1@example.com,user2@example.com"
      disallowLaunchByUser: false
      instructions: "Please review the build parameters and approve to continue"
      approvalInputs: |
        environment:
          type: choice
          options:
            - staging
            - production
        retry-count:
          type: number
          default: 3
        enable-monitoring:
          type: boolean
          default: true
    timeout-minutes: 4320
    delegates: cloudbees-io/manual-approval/custom-job.yml@v1

  deploy:
    needs: build-approval
    steps:
      - name: Deploy with approval parameters
        uses: docker://alpine:latest
        shell: sh
        run: |
          echo "Environment: ${{ fromJSON(needs.build-approval.outputs.approvalInputValues).environment }}"
          echo "Retry count: ${{ fromJSON(needs.build-approval.outputs.approvalInputValues).retry-count }}"
          echo "Monitoring enabled: ${{ fromJSON(needs.build-approval.outputs.approvalInputValues).enable-monitoring }}"▼

Manage workflows

After creating workflows, use these procedures to manage workflow execution, interface views, and ongoing maintenance.

Use workflow composer views

Configure the composer interface to suit your workflow creation preferences.

To adjust composer views:

Display only the visual tool by selecting Visual.
Display only the code editor by selecting Script.
Display both by selecting Split.
Resize composer width by dragging .

When Split is active: * Select to arrange the visual tool above the code editor. * Select to arrange the visual tool and code editor side by side.

Use the workflow code editor

Configure workflows directly in YAML format according to YAML formatting specifications.

To access the code editor:

Select the Edit YAML link for the workflow on the Workflows page.
Select the workflow name link on the Runs page.

The code editor provides direct YAML editing with real-time sync to the visual composer for supported workflow objects.

Save and commit workflows

To save workflow changes:

In the workflow Composer, select COMMIT.
Enter a Commit message.
Select a branch to commit to:
- Select Commit to current branch:<current branch>.
- Select Commit to new branch, then enter a new branch name.
- If committing to a new branch, optionally select Start a pull request to merge to <your default branch>.
Select FINISH.
Check your repository for the commit.

All CloudBees Unify workflows for your component are saved in .cloudbees/workflows in the connected repository.

Run workflows

Execute workflows manually when they have manual triggers configured.

To run a workflow:

In the Workflow composer, select Run (available when manual triggers are configured).
From workflow run details, select Rerun workflow or New run.

If the Run button is not present, add a manual trigger to enable manual workflow execution.

Remove job dependencies

To remove job dependencies:

Select the line connecting jobs to remove the needs relationship.
Review workflow execution order after removing dependencies to ensure proper job sequencing.

Create and manage workflows

Create workflows

Create standard workflows

Create staged workflows

Configure workflow components

Configure workflow settings

Configure workflow triggers

Manual triggers (workflow_dispatch)

Push or pull request triggers

Schedule triggers

Configure jobs

Configure standard jobs

Configure job steps

Configure services (Beta feature)

Configure stages

Configure manual approval jobs

Configure approval input parameters

Manual approval YAML reference

Required inputs

Optional inputs

YAML usage example

Manage workflows

Use workflow composer views

Use the workflow code editor

Save and commit workflows

Run workflows

Remove job dependencies

Related pages