CloudBees Unify workflows are YAML files in your repository that define automation for building, testing, scanning, and deploying software. A trigger starts a run, and the workflow’s jobs then run on CloudBees Unify-hosted infrastructure or on edge runners that you host. The same workflow engine supports continuous integration (CI) and release orchestration.
| This page covers the workflow engine itself. For how workflows fit into controlled release progression through environments, including approval gates, audit trails, and multi-component coordination, refer to Understanding release orchestration. |
Workflow structure
CloudBees Unify stores workflows in the .cloudbees/workflows/ directory of the repository that is connected to your component.
Each workflow has two main parts: triggers define when a run starts, and jobs define the work that the run does.
A job contains steps that run in order.
A step either runs shell commands with run or runs an action with uses.
Jobs that don’t depend on one another can run in parallel.
To make a job wait for others, list them in needs.
A job that has needs starts only after the jobs it depends on complete successfully.
For the exact syntax and the known differences, refer to Workflow syntax reference.
Triggers
A workflow can have one or more of five trigger types:
push-
Starts a run when commits or tags are pushed. You can filter by branch, path, and tag.
pull_request-
Starts a run on pull request activity, such as when a pull request is opened, updated, or closed. CloudBees Unify receives repository events through your SCM integration, so you don’t configure webhooks for individual workflows.
schedule-
Starts a run at times set by one or more cron expressions. Cron expressions use the UTC timezone, and scheduled runs execute only on the default branch of the repository.
workflow_dispatch-
Starts a run manually from the UI or the API, with optional input parameters. Only users with administrative permissions can start a manual run.
workflow_call-
Lets another workflow call this workflow as a reusable workflow.
For the properties of each trigger, refer to on.
Jobs
A job defines its work in one of three ways:
- Steps
-
A standard job lists its steps directly. Use standard jobs for build, test, scan, and deploy work.
- Reusable workflow (
uses) -
The job calls another workflow that has a
workflow_calltrigger. Reusable workflows can’t read the caller’s secrets or variables unless the caller passes them. The caller passes values as inputs, maps individual secrets and variables, or setssecrets: inheritorvars: inheritto share all of them. Explicit mapping limits what a reusable workflow can access;secrets: inheritgrants it everything the caller can reach. A call chain can include up to four levels of reusable workflows, including the caller. For details, refer to Create reusable workflows. - Custom job (
delegates) -
The job runs a pre-configured job template. Manual approval is a custom job that pauses the run until approvers respond. Approvers receive email notifications, and an unanswered approval times out after three days by default. For details, refer to Create and manage workflows.
A job times out after 60 minutes by default. You can raise the limit to 5760 minutes (four days) for standard jobs. A workflow run, including its approvals, must finish within four days.
Where jobs run
Jobs run either on CloudBees Unify-hosted infrastructure or on edge runners that you host.
Hosted execution
On CloudBees Unify-hosted infrastructure, each job runs in its own Kubernetes pod, so jobs don’t share an execution environment. The steps in a job run in containers that share the job’s workspace directory. Changes that a step makes to environment variables or to directories outside the workspace aren’t available to later steps.
Edge runners
Edge runners are self-hosted runners that execute jobs on your own infrastructure.
To send a job to an edge runner, set runs-on to one or more runner labels:
jobs: build: runs-on: [label1] steps: - name: Say hello run: echo "hello world"
A runner is eligible for a job only if it declares all the labels in runs-on.
If more than one eligible runner is available, any of them can pick up the job.
Runners that you create at the organization level are available to that organization and its sub-organizations.
Edge runners support all CloudBees Unify workflow features except sidecar services. You choose the job execution mode when you register a runner:
-
Docker mode runs jobs in isolated containers and is the default.
-
Native mode runs jobs directly on the host machine, and jobs can’t use actions.
Anyone who can create and run workflows in an organization where runners are available can run scripts on those runners. The execution mode and runner isolation level should fit your security requirements. For setup and security guidance, refer to Execute jobs with Edge Runners and Understanding Edge Runners security.
Workflow types
CloudBees Unify supports two workflow types:
- Standard workflows
-
Run build, test, scan, and deploy jobs, using the structure described on this page.
- Staged workflows
-
Organize a release into ordered stages, with approval gates, and coordinate activities across multiple components. Staged workflows are a Preview feature and connect to release orchestration. For how staged workflows work in a release, refer to Understanding release orchestration.
To create either type, refer to Create and manage workflows.
Connections to analytics, security, and artifacts
Workflow runs supply data to other areas of CloudBees Unify. Some of these connections work without extra configuration, and others need you to add steps or settings to the workflow.
- Analytics
-
The
kindproperty on a step tells CloudBees Unify how to categorize its data for analytics, such as DORA metrics, security insights, and test insights. The options arebuild,deploy,scan, andtest; steps without a kind are excluded from these analytics. For more information, refer to Understanding analytics in CloudBees Unify. - Security scanning
-
Implicit security assessment must be enabled for the implicit security analysis to run without a scan step in your workflow. It scans code when commits are pushed, and it analyzes binaries when a workflow completes successfully with an artifact publication step. Explicit Security analysis runs in your workflows using scanner actions. For more information, refer to Understanding application security posture management.
- Artifacts
-
Artifact information reaches CloudBees Unify through the register a build artifact action or through actions that register artifact data as a side effect, such as image promotion or Helm chart push actions. For details, refer to Manage workflow artifacts.
- Credentials and permissions
-
Workflows read secrets and variables through the
secretsandvarscontexts. Credential actions configure authentication for AWS, Git, and container registries for later steps in the same job. Thepermissionssetting controls a run’s access to the SCM token and the OIDC identity token, and job-level permissions override workflow-level permissions. For more information, refer to Understanding credential management andpermissions.