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_call trigger. 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 sets secrets: inherit or vars: inherit to share all of them. Explicit mapping limits what a reusable workflow can access; secrets: inherit grants 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 kind property on a step tells CloudBees Unify how to categorize its data for analytics, such as DORA metrics, security insights, and test insights. The options are build, deploy, scan, and test; 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 secrets and vars contexts. Credential actions configure authentication for AWS, Git, and container registries for later steps in the same job. The permissions setting 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 and permissions.