Manage workflows

Use the CloudBees platform workflow management features to configure workflows. Begin by accessing workflow management features. Then use the visual workflow composer and/or the code editor to configure workflow objects.

Access workflows

To access a workflow:

Select , and then select a component in an organization.
Select Workflows on the left panel to display the list of workflows.

Figure 1. Workflows list

Use these workflow management features:

Create a new workflow by selecting Create workflow.
Access a workflow YAML file.
- View the workflow YAML file by selecting the workflow name link.
- Modify workflow in the Composer by selecting Edit Yaml.
- Resize workflow viewer width by dragging .

Use the Composer visual editor to configure a workflow

Use the Workflow composer to create and configure workflows.

Use either the visual tool and YAML scripting, or both together, to compose your workflow. Updates made with the visual tool or the code editor are automatically displayed in both.

Open a workflow in the Workflow composer one of the following ways:

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

Figure 2. Workflow composer

Use the following feature to configure a workflow:

Use the Workflow composer to:
- Switch the repository branch by selecting branch name.
- Exit workflow composer without saving changes by selecting Cancel.
- Save changes to the workflow by selecting Commit.
- Trigger a new workflow run by selecting Run.
  
  If the Run is not present, add a manual trigger. Refer to Configure a manual trigger.
Configure workflow settings or triggers
- Modify workflow name and env key/value pairs by selecting settings.
- Select Trigger to add a new or to edit an existing push, pull, manual, or schedule trigger.
Configure a standard or approval job
- Create a new job by selecting Job or Approval and then dragging it to the job area of the visual composer.
- Modify an existing joby by selecting the next to a job, and then select Edit.
- Remove job needs object by double-clicking on the line connecting jobs.
Adjust the composer view.
- Resize composer width by dragging .
- Display only the visual tool by selecting Visual
- Display only the code editor selecting Script
- Display both by selecting Split.
  
  When SPLIT is active, select to arrange the visual tool above the code editor, or select to arrange the visual tool and code editor side by side.

Use the workflow code editor

Use the workflow code editor to configure a workflow according to YAML formating specifications. For additional details related to configuring workflow objects refer to:

To use the code editor begin by opening a workflow in the Workflow composer one of the following ways:

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

Figure 3. Code editor

Save a workflow

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

Figure 4. Commit workflow
Check your repository for the commit.

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

Configure a `push` or `pull_request` trigger

Configure a workflow run to start with a push or pull-request.

To configure a push or pull-request trigger:

Use the code editor to configure push or pull trigger. Refer to CloudBees DSL syntax for code details.

View push and pull trigger code examples

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Example 2
on:
  push:
    branches:
      - "**"
    tags:
      - git-tag-name
  pull_request:
    branches:
      - main
jobs:
  build:
    steps:
      - name: Say hello
        uses: docker://golang:1.20.3-alpine3.17
        shell: sh
        run: |
          echo "hello world"▼

Access trigger configuration features via the workflow Composer.
- Create a new trigger by selecting Trigger or drag Trigger to the trigger area of the visual composer.
- Modify an existing trigger by selecting the next to a trigger, and then choosing Edit.

Figure 5. Edit push or pull trigger

Use these features to configure a push or pull-request trigger.

Configure push or pull-request
- 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.
- Choose one or more git tags for a push trigger in the Tags field by:
  - Defining a tag patten names. (Recommended) e.g. "v*"
  - Entering a specific tag name. e.g. "v1.0"
Manage trigger.
- Remove a branch by selecting next to a branch.
- Exit and discard changes by selecting Cancel
- Keep trigger configuration changes.
  1. Select Save. The schedule trigger is displayed in the visual composer trigger section and in the code editor: on: push or pull-request.
  2. Continue workflow configuration one of the following ways:
    
    Use the code editor to configure additional workflow attributes. Refer to Code editor.
    
    Finalize changes by saving the workflow.

Configure a workflow_dispatch trigger

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

Use the workflow_dispatch trigger to allow users with the proper permissions to manually trigger a workflow run. Add input parameters to the trigger to customize workflow runtime behavior. For example, use a parameter to select the deployment environment, enable or disable a feature during deployment, or select a server or service to deploy.

Avoid using parameters these types of data as parameter
Access tokens	Payment information
Binary data	Personally identifiable information
Encryption keys and certificates	Private keys
Large data files	Secrets and passwords
Long strings or complex data structures	Sensitive configuration files

Avoid using parameters these types of data as parameter

Access tokens

Payment information

Binary data

Personally identifiable information

Encryption keys and certificates

Private keys

Large data files

Secrets and passwords

Long strings or complex data structures

Sensitive configuration files

Once configured, a user with proper permission can trigger a workflow using the:

Composer visual editor by selecting Rerun workflow, New run, or the manual trigger button.
Run details: Select Rerun workflow or New run button.

To configure a manual trigger:

Use the code editor to configure a schedule trigger. Refer to CloudBees DSL syntax for code details.

View manual trigger with input parameters

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Example 2
on:
  workflow_dispatch:
    inputs:
      stringIn:
        type: string
        default: String input value
        required: true
        description: Input string
      pickList:
        type: choice
        options:
          - abc
          - def
          - ghi
        default: abc
        description: Pick list description
      booleen:
        type: boolean
        default: true
        description: A Boolean entry
      RetryCount:
        type: number
        default: 3
        required: true
        description: Retry deployment a certain number of times.
jobs:
  build:
    steps:
      - name: Say hello
        uses: docker://golang:1.20.3-alpine3.17
        shell: sh
        run: |
          echo "hello world"▼

Access trigger configuration features via the workflow Composer.
- Create a new trigger by selecting Trigger or drag Trigger to the trigger area of the visual composer.
- Modify an existing trigger by selecting the next to a trigger, and then choosing Edit.
Figure 6. Edit manual trigger

Use these feature to configure a manual trigger.

Configure a manual trigger:
- Ensure Manual is the selected Type option.
- Change parameter order.
  1. Select a parameter .
  2. Drag the step to new location in parameter sequence.
- Create up to 10 input parameters.
  1. Select + add parameter.
  2. Select an input parameter type from the menu options.
    
    View parameter type definitions
    
    String: Allows users to input a text-based value, which can then be used within the workflow to control behavior, pass data, or configure settings.
    
    Number: This function accepts numerical inputs, allowing users to specify integer or floating-point values. For example, you can allocate the number of CPUs or memory units to set a threshold such as error_threshold: 100. You can also manage versions, timeouts, and IDs.
    
    Boolean: This parameter type accepts binary values: true or false. It is ideal for toggling features, enabling or disabling specific steps, or controlling conditional logic within a workflow.
    
    Choice: This parameter allows users to select a single option from a predefined list of choices. It is particularly useful to guide user input to specific, valid options, ensuring consistency and reducing the risk of errors.
    
    Enter a name for the parameter.
    
    Complete applicable fields
    
    Enter a description for the parameter.
    
    Enter a default parameter value. This value is applied when value is provided in the request.
    
    Make the parameter value required in the request by selecting Required.
    
    If true, an error occurs when no value is provided for the parameter in the request and no default value is defined.
    
    View trigger input parameters
    
    apiVersion: automation.cloudbees.io/v1alpha1 kind: workflow name: Example 2 on: workflow_dispatch: inputs: stringIn: type: string default: String input value required: true description: Input string pickList: type: choice options: - abc - def - ghi default: abc description: Pick list description booleen: type: boolean default: true description: A Boolean entry RetryCount: type: number default: 3 required: true description: Retry deployment a certain number of times. jobs: build: steps: - name: Say hello uses: docker://golang:1.20.3-alpine3.17 shell: sh run: | echo "hello world"
    ▼
Complete manual approval trigger configuration:
- Exit and discard changes by selecting Cancel.
- Keep schedule trigger configuration changes.
  1. Select Save. The manual trigger is displayed in the visual composer trigger section and in the code editor: on: workflow_dispatch:.
  2. Continue workflow configuration one of the following ways.
    
    Use the code editor to configure additional workflow attributes. Refer to Code editor.
    
    Finalize changes by saving the workflow.

Configure a schedule trigger

Use the schedule trigger to start a workflow run according to configured cron schedules. Scheduled triggers execute only on the default branch of the repository.

Cron expressions are configured in UTC timezone.

Once configured, workflow runs triggered by this schedule appear in the Runs list with trigger by details similar to:

#592 Scheduled At 0, 10, 26, 33, 40, and 50 minutes past the hour, every hour, every day (UTC).▼

Configure a schedule trigger:

Use the code editor to configure a schedule trigger. Refer to CloudBees DSL syntax for code details.

View schedule trigger code examples

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Example 2
on:
  push:
    branches:
      - "**"
  schedule:
    - cron: 0 7 1 * 1,2,3,4
    - cron: 0 14 * * 1,2,3,4
    - cron: 0 15 * * 1,2,3,4
    - cron: 0 16 * * 1,2,3,4
jobs:
  build:
    steps:
      - name: Say hello
        uses: docker://golang:1.20.3-alpine3.17
        shell: sh
        run: |
          echo "hello world"▼

Access trigger configuration features via the workflow Composer.
- Create a new trigger by selecting Trigger or drag Trigger to the trigger area of the visual composer.
- Modify an existing trigger by selecting the next to a trigger, and then choosing Edit.
Figure 7. Edit trigger

Use these features to configure a schedule trigger:

Configure schedules
- Ensure Schedule is the selected Type option.
- Enter schedules in cron format.
Manage schedules
- Create schedules by selecting + new schedule.
- Remove a schedule by selecting next to a schedule.
- Exit and discard changes by selecting Cancel.
- Keep schedule trigger configuration changes.
  1. Select Save. The schedule trigger is displayed in the visual composer trigger section and in the code editor: on: schedule.
  2. Continue workflow configuration one of the following ways.
    
    Use the code editor to configure additional workflow attributes. Refer to Code editor.
    
    Finalize changes by saving the workflow.

Configure a workflow call trigger

Use the workflow_call trigger to enable a workflow to be called to execute as a reusable workflow job.

To configure a workflow_call trigger, use the code editor to configure a workflow call trigger. Refer to Reusable workflows for code details.

Configure a standard job

To configure a standard job:

Use the code editor to configure an approval job. Refer to CloudBees DSL syntax for code details.
Access job configuration features via the workflow Composer.
- Create a new job by selecting Job or drag Job to the job area of the visual composer.
- Modify an existing job by selecting the next to a job, and then choosing Edit.
  
  Figure 8. Edit job

Use these features to configure a standard job.

Complete applicable job fields.
- Enter name for the job.
- Indicate the job or jobs that must complete successfully before the job runs by selecting Add needs.
- Specify a job run environment by selecting the name from the Environment options.
Manage services.

Services is a Preview feature.
View Service management information
1. Access service configuration fields of the following ways.
  
  Configure new service by selecting the Add service link.
  
  Modify an existing service by to create a or the next to a service, and then choosing Edit.
2. Complete applicable service configuration fields:
Figure 9. Service
- Enter a name for the service.
- Enter the docker image name or tag.
- Specify the service environment by selecting the name from the Add environment options.
- The argument values will override the values in the CMD Dockerfile. For details related service arg syntax, refer to jobs.<job_id>.services.<service_id>.args
Manage steps.
- Change job step order.
  1. Select a step .
  2. Drag the step to a new location in the job sequence.
- Delete the step by selecting in the step header, and then choosing Delete.
- Create a new or modify an existing step.
  1. Access step configuration fields one of the following ways.
    
    Create a new step by selecting the Add step link.
    
    Modify an existing step by selecting next to a step, and then choosing Edit.
  2. Complete applicable step configuration fields:
    
    View image of Step fields
    
    Figure 10. Step
    
    Enter a name for the step.
    
    Locate and select a preconfigured action or container to execute the job from the Uses field options, or Select from catalog to search the catalog.
    
    Select a Kind option (other than None) to use the data from this step for analytics calculations.
    
    Select Deploy to use DORA metrics.
    
    Select Build to use Software delivery activity.
    
    Select Scan to use Security insights.
    
    Select Test to use Test insights.
    
    If the Kind option is inappropriate for the step, the data is not collected.
Modify job
- Specify a job output key value pair by selecting Add output.
- Exit and discard changes by selecting Cancel.
- Keep job configuration changes.
  1. Select Save. The standard job is displayed in the visual composer and in the code editor, under jobs:.
  2. Continue workflow configuration one of the following ways.
    
    Use the code editor to configure additional workflow attributes. Refer to Code editor.
    
    Finalize changes by saving the workflow.

Configure a manual approval job

Add a Manual approval custom job to insert a workflow approval. Once set up, approvers will be notified via email that an approval response is required.

To configure a manual approval job:

Use the code editor to configure an approval job. Refer to Manual approval for code details.
Access job configuration features via the workflow Composer.
- Create a new job by selecting Job or dragging Job to the job area of the visual composer.
- Modify an existing job by selecting the next to a job, and then choosing Edit.
Figure 11. Create manual approval

Use these features to configure a manual approval job.

Complete applicable fields.

Enter a name for the approval job.
Review or modify the timeout-minutes default value of 4320 minutes. This is the number of minutes approvers have to respond to the approval request.

To specify a job or jobs that must successfully complete before the approval job runs.

Select Add needs.

Select the name of the job.

Use needs along with outputs context to access parameter input values.

To return:

All parameter input values provided by a workflow approver in JSON format: needs syntax of ${{needs.<approvalJobName>.outputs.approvalInputValues}}
A specific approval parameter input value: ${{ fromJSON(needs.<approvalJobName>.outputs.approvalInputValues).<parameterName> }}.

Select the name of users who can approve the workflow run. Both user IDs and email addresses are supported Approvers field values.

Approval rules and notifications are as follows:
- If approvers are specified, then:
  - only listed approvers will receive email notification.
  - only listed approvers can participate in approval process.
- If approvers are not specified, then:
  - only the workflow initiator will receive email notification.
  - all eligible users can participate in approval process.
Enter instructive text for the approvers. This text will be visible in the approval email notification and run details.
Ensure that the person who starts the workflow cannot approve workflow by selecting Disallow workflow initiator from approving.

Manage input parameters.
- Change parameter execution order.
  1. Select a parameter .
  2. Drag the parameter to a new location in the execution sequence.
- Remove a parameter by selecting .
- Create a new or modify an existing input parameter.
  1. Access input parameter configuration fields one of the following ways.
    
    Create a new parameter by selecting the Add input link.
    
    Modify an existing parameter by selecting the parameter .
  2. Modify parameter values.
    
    View input parameter code examples
    
    build-approval: with: approvalInputs: | string-value: type: string retry-count: type: number booleen: type: boolean default: false Picklist: type: choice options: - abc - xyz
    ▼
Complete approval job configuration.
- Review the default output values for the approval job by selecting Expand all.
- Exit and discard changes by selecting Cancel.
- Keep job configuration changes.
  1. Select Save. The approval job is displayed in the visual composer and in the code editor, under jobs:
    
    Approval input parameters are listed under approvalInputs
    
    delegates value of https://github.com/cloudbees-io/manual-approval/custom-job.yml@v1
  2. Continue workflow configuration one of the following ways.
    
    Use the code editor to configure additional workflow attributes. Refer to Code editor.
    
    Finalize changes by saving the workflow.

Configure a reusable workflow job

Add a reusable workflow job to call a pre-configured workflow to execute as a workflow job.

Use the code editor to configure a reusable workflow job. Refer to Reusable workflows for code details.

Currently reusable workflow job creation is not supported in the CloudBees platform UI.

Associate run data with analytics dashboards

To populate all analytics dashboards, you must first create a component and a workflow. To pull data into specific dashboards, you must additionally specify the kind of workflow step, as detailed below:

DORA metrics requires both Build and Deploy.
Security insights requires Scan.
Test insights requires Test.

In the code editor, use the kind keyword in your workflow steps to populate analytics dashboards. If using the visual tool, specify the kind of step by selecting a Kind option other than None, as in the following example:

Figure 12. Scanning step with Scan kind selected.

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

In the following workflow job example, the build, test, and scan steps are specified.

jobs:
  ci-job:
    steps:
      - uses: docker://alpine/git:latest
        run: |
          git config --global --add safe.directory /cloudbees/workspace
      - uses: cloudbees-io/checkout@v1
        name: checkout
      - uses: docker://golang:1.20
        name: Build Go app
        kind: build (1)
        run: |
          go build -v ./...
      - uses: docker://golang:1.20
        name: Run tests
        kind: test (2)
        run: |
          go test -v ./...
      - uses: cloudbees-io/sonarqube-bundled-sast-scan-code@v1
        name: Scan with SonarQube bundled
        kind: scan (3)▼

1	Build step specified.
2	Test step specified.
3	Scan step specified.