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 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 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.
Manual - Enables users with permission to manually trigger workflow runs via the CloudBees platform UI or API by users with permission. For details refer to: Configure manual trigger and Trigger a workflow remotely

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

Standard - Contains at least one step with a valid uses entry.
Custom - A job that executes within a workflow job using the delegates object. Refer to jobs.<job_id>.delegates for details.
Manual approval is currently the only custom job. 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.