Manage workflows

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

Triggers: These are events that start a workflow run. Triggers are displayed in the Trigger section of the visual composer and under on in the code editor.

There are four types of triggers.
- Push - Starts the workflow based upon a push request and git tags.
- Pull - Starts the workflow based upon a pull request.
- Schedule - Starts the workflow based upon configured cron schedules. There is no limit on the number of schedules.
- Manual - Allows users with permission to trigger a workflow run.
Jobs: Workflow activities.

There are two types of jobs.
- Standard - Contains at least one step with a valid uses entry.
- Custom - A job that executes the workflow job using the delgates object.
- Manual approval is currently the only custom job. Configure a manual approval job to require an approval of the workflow run. Refer to:
  - Configure a manual approval
  - Manual approval custom job

Access Workflows List

To access a workflow:

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

Figure 1. Workflows list

Use these workflow management features:

Create a new workflow by selecting Create workflow.
Access 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 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 manual trigger

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

Add a manual trigger to the workflow to allow users with the proper permissions to 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.

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 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.

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 job run environments by selecting the name from the Environment options.
Use these features to configure steps.
- Delete the step by selecting the in the step header, and then select Delete.
- Enter a name for the step.
- Locate and select a preconfigured action or container to execute the job from the in Uses field options or click Select from catalog to search the catalog.
- Change job step order.
  1. Select a step .
  2. Drag the step to new location in job sequence.
- 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
- Create a new job step by selecting Add step link.
- Specify step 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.

View manual approval code example

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Example 2
on:
  push:
    branches:
      - "**"
jobs:
  build:
    steps:
      - name: Say hello
        uses: docker://golang:1.20.3-alpine3.17
        shell: sh
        run: |
          echo "hello world"
  workflow-approval:
    timeout-minutes: 4320
    delegates: cloudbees-io/manual-approval/custom-job.yml@v1
    with:
      approvers: de39a936-7a04-11ec-81d0-42010a83ae75
      disallowLaunchByUser: true
      notifyAllEligibleUsers: true
      instructions: "Enter instructive text for approvers here. "▼

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.

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.
  1. Select Add needs.
  2. Select the name of the job.
- Select the name of users who can approve the workflow run. Both user IDs and email addresses are supported.
- 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.
- Specify who will receive notification to participate in workflow approval process by selecting Notify all eligible users.
  
  Notifications will be sent as follows:
  - If users are listed in Approvers and Notify all eligible users is true or false, then
    
    Only listed approvers will receive notification.
    
    Only listed approvers can participate in approval process.
  - If Approvers is blank and Notify all eligible users is false, then
    
    No notifications will be sent.
    
    All eligible users can participate in approval process.
  - If Approvers is blank and Notify all eligible users is true, then
    
    The CloudBees platform will select and notify up to 10 eligible users.
    
    All eligible users can participate in approval process.
Complete approval job configuration.
- 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: with delegates value of 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.