CloudBees platform workflows

CloudBees workflows are DevOps automations that run one or more jobs. Define each workflow by a YAML file in a .cloudbees/workflows directory in your repository.

Your repository can have multiple workflows, each of which can perform a different set of tasks. For example, you can have one workflow to build and test pull requests, and another workflow to build and deploy your application.

If a particular task in a workflow is to be reused, you can save it as an action. Both unique scripts and actions can be used together in any workflow.

Workflow minimum requirements

The minimum requirement for a workflow is as follows:

A repository event to trigger the workflow.
At least one job composed of at least one step.
A job step must contain either a script that you define, or a predefined action.

Workflow keywords and parts

Refer to An example workflow to understand how each keyword or part is used in a workflow.

Refer to specific actions in CloudBees actions for other workflow keywords.

Table 1. Definitions of workflow keywords and parts
Keyword or part	Definition
`apiVersion`	Specifies the CloudBees DSL syntax version, for example, `automation.cloudbees.io/v1alpha1`.
`kind`	Specifies the kind of CloudBees DSL file, for example, `workflow`.
`name`	(Optional) Specified for a workflow, this name is also displayed in your component Workflows and Runs, instead of the default filename. (Optional) Specified for a step, this name is displayed in your component Runs, instead of the default action or container name (from the `uses:` statement).
Event	A repository commit, or creation of a pull request. An event triggers a workflow to start.
`on`	Groups all repository events that can trigger a workflow to start.
`env`	Defines a list of local properties. Each property is a key / value pair. The location of `env` determines the property scope; for example, if `env` is nested in a job, the properties are only visible to that job and its steps.
`job`	A group of steps that run in the workflow. By default, jobs are run in parallel. Also, job usage is limited to 4G memory and 4000m CPU (4 vCPUs).
`needs`	Multiple jobs in a workflow can be run sequentially, by specifying the name, in `needs`, of the job that must be finished successfully before the current job can start.
`steps`	Steps are activities that occur in series within a workflow job. Containerized custom scripts or action calls are common step examples. Steps execute: In a specified order. On the same dedicated Kubernetes pod, through the Tekton Pipelines engine.
`id`	(Optional) The step ID. Subsequent steps can refer to outputs produced by this step by using its ID, for example, `${{ steps.aws-login.outputs.aws-account-id }}`.
Action	A saved script that performs a task, and increases coding efficiency by its reuse in workflows. For more information, refer to CloudBees actions.
`uses`	Within a step, specifies an action to use, or where a custom script is to be run. For example: Run tag v1 of the CloudBees action: Check out a Git repository, by specifying `cloudbees-io/checkout@v1`. Run a step command in a Docker container, by specifying `docker`.
`shell`	Specifies the shell used to run a step command.
`run`	Specifies a command to run in a step.
`with`	Groups all parameters a step uses during execution. Each parameter is a key / value pair.
`outputs`	Groups all job outputs, and makes them available to downstream jobs. Each output is a key / value pair.

Ensure that your workflow and action code do not execute untrusted input. Use the following recommendations to harden your code against attackers:

Use CloudBees platform actions instead of an inline script to pass the context value to the action as an argument.
Store sensitive information in secrets.
Add a code scanner step to your workflow to check for security vulnerabilities.
Add the .cloudbees/workflows directory to the code owners list.
For inline scripts, use an intermediate environment variable to handle untrusted input.