Manage workflows

Automate development with CloudBees platform workflows. Workflows are configurable processes, defined in a YAML file, which 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 the , and then select a component in an organization.
Select Workflows on the left pane.
(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.

You are displaying workflows for your component, listed in alphabetical order.

Create and save a workflow

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

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

To create and save a workflow:

Select the , 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 either 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, and then enter a new branch name.
- If committing to a new branch, you may also optionally select Start a pull request to merge to <your default branch>.
Select FINISH.

Figure 2. Committing 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, push, or manual trigger.
Select JOB to add a job.
Select the to update the trigger.
Select the to update a job or add a step.
Slide to expand or shrink the workflow display size.

Manage workflow triggers

You can create up to three different workflow trigger types:

Push event
Pull request event
Manual

To save your trigger, commit your changes, and the next run incorporates the updates. You can update or delete a trigger type, but you may only have a single trigger of each type.

Create an event trigger

Trigger a workflow to execute with a push and/or a pull-request event.

To set up an event trigger in the visual composer:

Select TRIGGER.
Select Push or Pull request from the Type options.
Select one or more Branches from the options.

Select the to remove a branch from the repository branch list. ** denotes any branch name, so 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

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

You must have administrative permissions to run a manual workflow.

To set up a manual trigger in the visual composer:

Select TRIGGER or drag TRIGGER to the trigger area of the visual composer.
Select Manual from the Type options.
Select SAVE.
Select COMMIT to update your workflow.

The manual trigger is set up and displayed in both the visual composer and code editor (as workflow_dispatch:). You must now 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 the or the RUN to manually trigger a workflow.

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

The following example workflow runs in response to any of three types of triggers:

Figure 6. Example workflow with all three types of triggers (highlighted in the code editor).

Update a workflow trigger

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

To update an existing workflow trigger in the visual composer:

Select the next to the trigger you want to update.
Select Edit.
Change the Type if desired. Only types that have not yet been created 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 both 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 the next to the trigger you want to update.
Select Delete.

The deleted workflow trigger type is removed from both 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 7. 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 complete before another runs, either select ADD NEEDS or drag the job to the correct position in the visual tool.

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

Add a step to a job

To add a step to a job:

Select the 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, which opens the list of actions and containers.
2. Enter an action or container to Uses.
  
  Figure 9. 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 10. Required inputs entered for Snyk SCA scan action.

(Optional) Select from the Kind options.

Figure 11. 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 the , 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, and then enter a new branch name.
- If committing to a new branch, you may also 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 the , and then select a component in an organization.
Select Workflows on the left pane.
Select the workflow link.
Select the next to the workflow filename.
Select Delete.
Select CONFIRM.

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