CloudBees platform workflows

CloudBees workflows are DevOps automations that run one or more jobs. Each defined workflow is saved in YAML format in the .cloudbees/workflows repository directory. Use unique scripts, actions or custom jobs to execute workflow jobs.

Workflow types

There are two types of CloudBees platform workflows.

Standard: Use this workflow for build and deployment automations.
Staged: Use to organize release activities into stages for end-to-end process management.

Workflow parts

Workflows are comprised of at least one trigger and job.

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

There are five types of triggers.

push - Starts the workflow based upon a push request. For more information, refer to:
- push usage examples
- Configure a push or pull_request trigger
pull_request - Starts the workflow based upon a pull request and Git tags. For more information, refer to:
- pull_request usage examples
- Configure a push or pull_request trigger
schedule- Starts the workflow based upon configured cron schedules. For more information, refer to:
- schedule usage examples
- Configure a schedule trigger
workflow_dispatch - Enables users with permission to manually trigger workflow runs via the CloudBees platform UI or API. For details refer to:
workflow_call - Enables a workflow to be called to execute as a reusable workflow job. For more information, refer to:
- workflow_call usage examples
- Reusable workflows for details
- Configure workflow_call trigger for UI setup details .

There are three types of jobs. Each job type can be used in a workflow, but a job can only be one type.

Standard: Must contain at least one step with a valid uses: entry.
Reusable workflow job: Calls a workflow by setting uses: to the repository path of the reusable workflow yaml file.
Custom:
- A job that executes within a workflow job using the delegates object. Refer to jobs.<job_id>.delegates for DSL syntax details.
  
  Manual approval is currently the only custom job available.
- Configure a manual approval job to require an approval within a workflow run, refer to:
  - Configure Manual approval job
  - Manual approval custom job

Common workflow keywords

Use the code editor to configure workflow job objects. For additional details related to configuring workflow objects, refer to:

Table 1. Common workflow objects
Keyword	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`	Use to specify workflow or step name. If a workflow `name` value is not found then the file name is used as the default. If a step `name` value is not found then the `uses` value is the default.
`on`	The `on` workflow section contains all workflow trigger configurations.
`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).
`delegates`	Use to delegate execution of a workflow job to a custom job.
`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.
`uses`	Configure to specify an action or script to use to execute the step.
`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.
`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 }}`.
`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.