Manage workflows

Automate development with CloudBees platform workflows. The Workflows are configurable processes defined in a YAML file that run jobs. Trigger your workflow manually or by an event in your integrated repository.

Refer to the following for detailed information on scripting a workflow YAML:

Access a workflow

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.
(Optional) Select the next to Rows per page to display more workflows, or select the to advance to the next page.
(Optional) Choose one of the following:
- Select a workflow name to display the workflow file.
- Select Edit YAML to update the workflow.
- Select Create workflow to create a new workflow.

Workflows for your components are displayed alphabetically.

Create a workflow

Create any number of workflows using the workflow composer. Switch between the visual tool and the code editor to compose or update your workflow.

You must commit to your repository or open a pull request to save your workflow. You can commit to either the current branch or a new branch.

To create and save a workflow:

Select , and then select a component in an organization.
Select Workflows on the left pane.
Select Create workflow to display a default workflow.

Figure 1. Default workflow in the visual tool and code editor.
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.
- Select Visual to display only the visual tool.
- Select Script to display only the code editor.
- Select Split to display both the visual tool and the code editor.
  
  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.
Select Commit.
Enter a Commit message.
Select a branch to commit to from the 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 2. Commit to a new branch, with Finish highlighted.
Check your repository for the commit.

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

Figure 3. Commit in the connected GitHub repository.

Your workflow is created and listed in Workflows.

Use the workflow composer visual tool

The visual tool enables you to compose and update a workflow using the UI.

Any changes in the visual tool are reflected in the YAML script.

Figure 4. Visual tool features.

As highlighted above, use the visual tool to perform the following activities:

Switch the repository branch.
Select Settings to update the workflow name and input any env key/value pairs.
Select Trigger to add a pull request, or a manual trigger.
Select Job to add a job.
Select to update the trigger.
Select to update a job or add a step.
Slide to expand or shrink the workflow display size.

Manage workflow triggers

You can create a trigger from these workflow trigger types:

Push
Pull request
Manual
Schedule

You can also trigger a workflow remotely, using a platform-generated API. Refer to Trigger a workflow remotely for more information.

To add a trigger to a workflow, you must define it, commit the changes, and save it. The next run incorporates the updates. You can update or delete a trigger, but only one of each type is permitted.

Create an event trigger

Trigger a workflow to execute with a pull-request.

To set up an event trigger in the visual composer:

Select Trigger.
Drag and drop the Trigger to the correct position in the visual tool.

Figure 5. Place Trigger into the workflow using the visual editor.
Select Pull request from the Type options.
Select one or more Branches from the options.

Select to remove a branch from the repository branch list. ** denotes any branch name, remove ** to allow only specific branches to trigger a workflow.
Select Save.

The workflow trigger is displayed in the visual composer and in the code editor, under on:.

You must now commit your work to update and save the workflow.

Create a manual trigger with input parameters

Set up a manual trigger to run the workflow on demand (without an event).

Use input parameters to customize your workflow’s behavior at runtime, adapting it to various scenarios without modifying the workflow definition. For example, you can use a parameter to select the deployment environment, enable or disable a feature during deployment, or select a server or service to deploy.

You must have administrative permissions to run a manual workflow.
Currently, input parameters are only available for manual triggers.

Avoid using parameters for:

Secrets and passwords
Private keys
Large data files
Binary data
Sensitive configuration files
Long strings or complex data structures
Personally identifiable information
Encryption keys and certificates
Payment information
Access tokens

To set up a manual trigger in the visual composer:

Select Trigger or drag Trigger to the trigger area of the visual composer. This opens the Create trigger dialogue.
Select Manual from the Type options.
(Optional) Select + add parameter

You can add up to 10 input parameters.

Figure 6. Create a manual trigger and add an input parameter.

Select the parameter type.

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.

View an example

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Example 1


on:
 workflow_dispatch:
  inputs:
    Deployment_version:
      type: string
      default: latest
      required: true
      description: "Specify the version (for example, v1.0, v736) of the application to deploy."
jobs:
build:
  steps:
    - name: Deploy application
      uses: docker://alpine:3.13
      shell: sh
      run: |
         echo "Deployment of version ${{inputs.Deployment_version}}"▼

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.

View an example

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Example 2
on:
workflow_dispatch:
  inputs:
    RetryCount:
      type: number
      default: 3
      required: true
      description: Retry deployment a certain number of times.
jobs:
build:
  steps:
    - name: Retry deployment
      uses: docker://golang:1.20.3-alpine3.17
      shell: sh
      run: |
        for i in $(seq 1 ${{inputs.RetryCount}}); do
          echo "Attempt $i"
        done▼

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.

View an example

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Example 3
on:
workflow_dispatch:
  inputs:
    checkenv:
      type: boolean
      default: true
      description: Check the environment, then deploy to production.
jobs:
build:
  steps:
    - name: Check environment
      uses: docker://golang:1.20.3-alpine3.17
      shell: sh
      run: |
        if [ "${{inputs.ceckenv}}" = "true" ]
        then
          echo "Deploying to production"
          # Production deployment steps
        else
          echo "Deploying to staging"
          # Staging deployment steps
        fi▼

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.

View an example

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Example 4
on:
workflow_dispatch:
  inputs:
    Select-env:
      type: choice
      options:
        - dev
        - staging
        - production
      default: dev
      required: true
      description: Select the environment for deployment.
jobs:
build:
  steps:
    - name: Deploy to the selected environment
      uses: docker://golang:1.20.3-alpine3.17
      shell: sh
      run: |
        echo "Deploying to ${{inputs.Select-env}} environment"
        # Add deployment steps based on the selected environment▼

Type a parameter name.
(Optional) Type a description.
(Optional) Type a default value.

If no value is provided for the parameter in the request, the default value is applied
(Optional) Select Required.

If set to true, an error will occur if no value is provided for the parameter in the request and no default value is defined.
Select Save.

The manual trigger with its parameter(s) is displayed in the visual composer and code editor (as workflow_dispatch:).
Select Commit.

You must commit your work to update and save the workflow.

Manually trigger a workflow

Once you have created a manual trigger in a workflow and saved it with a commit, use it to run workflows on demand.

Select or Run to manually trigger a workflow.

Figure 7. Select Run (highlighted) to trigger a workflow manually.

The workflow shown in the image below will run when triggered by any of the three specified types of events.

Figure 8. Example workflow with three types of triggers (highlighted in the visual editor).

Configure a schedule trigger

Configure a workflow to start based on 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 a trigger 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 example

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Example 2
on:
  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 the following trigger configuration features via the workflow Composer:
- Create a new trigger by selecting Trigger or drag the 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 9. Edit schedule trigger

Use these features to configure a schedule trigger:

Configure schedules
- For Type, select the Schedule option.
- Enter schedules in cron format.
Manage schedules
- Create up to 12 schedules by selecting + new schedule.
- Remove a schedule by selecting next to the 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.

Update a workflow trigger

Once a trigger type is selected, update the repository branches or change to a different type.

To update an existing workflow trigger in the visual composer:

Select next to the trigger you want to update.
Select Edit.
Change the Type if desired. Only the types that have not yet been selected are available.
(Optional) For an event trigger, select or deselect Branches from the options. You must select at least one branch.
Select Save.

The updated workflow trigger is displayed in the visual composer and code editor. You must now commit your work to update and save the workflow.

Delete a workflow trigger

Remove a trigger type from a workflow.

Select next to the trigger you want to update.
Select Delete.

The deleted workflow trigger type is removed from the visual composer and code editor. You must now commit your work to update and save the workflow.

Add a job

In the following example, selecting Job and adding the job details creates a new job.

Figure 10. Created job with Job and needs input highlighted.

The MavenBuild job requires the Checkout job to run successfully first. To specify that a job must be completed before another run, select Add needs or drag the job to the correct position in the visual tool.

Figure 11. Dragging the Checkout job to run before the MavenBuild job.

Add a step to a job

To add a step to a job:

Select next to your job, and then select Edit.
Select Add step.
(Optional) Enter a step name.
Do either of the following:
1. Choose Select from catalog to add a preconfigured action, action, or container that opens the list of actions and containers.
2. Enter an action or container to Uses.
  
  Figure 12. Example of searching, with selection and Apply selected highlighted.
Enter any required inputs that are not already pre-populated. Inputs marked with an are required.

Figure 13. Required inputs entered for Snyk SCA scan action.

(Optional) Select from the Kind options.

Figure 14. Scanning step with Scan kind selected.

Select an appropriate Kind option (other than None) to associate the data from this step for analytics calculations. If the Kind option is inappropriate for the step, the data are not counted.

Select Deploy to use DORA metrics.
Select Build to use Software delivery activity.
Select Scan to use Security insights.
Test-related metrics are coming soon.

Select Save.

The step is added to the workflow job in the code editor and in the visual tool.

Use the workflow composer code editor

Input your workflow script directly into the code editor. Cut, copy, and paste as you would in any code editor. You can also undo and redo input.

Use the correct YAML indentation according to the specifications. Any invalid YAML is highlighted with a wavy underline.

Update and save a workflow

Update your workflow with either the visual tool or the code editor in the composer.

To update a workflow:

Select , and then select a component in an organization.
Select Workflows on the left pane.
Select Edit YAML next to a workflow.
Make any desired changes with either the visual tool or the code editor.
Select a repository Branch from the options.
Select Commit.
Enter a Commit message.
Select a branch to commit to from the 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.
Check your repository for the commit.

Your workflow is updated accordingly, and the changes are committed to your repository, triggering a workflow run.

Delete a workflow

Delete any of your workflows. A deleted workflow is completely removed from the CloudBees platform, and deletion is irreversible.

To delete a workflow:

Select , and then select a component in an organization.
Select Workflows on the left pane.
Select the workflow link.
Select next to the workflow filename.
Select Delete.
Select Confirm.

Your workflow is deleted, and removed from your workflow list.