Workflow syntax reference

Workflow syntax defines the structure and metadata for CloudBees Unify workflows, including naming, triggers, environment configuration, and permissions. Use this reference when configuring workflow-level properties and trigger conditions.

CloudBees Unify workflow syntax is based on GitHub Actions (GHA) syntax. Some GHA features aren’t supported, and some behave differently. If a GHA feature isn’t listed in this reference, don’t assume CloudBees Unify supports it. For known differences, refer to Differences from GitHub Actions.

Required metadata

Every workflow file starts with metadata that identifies it as a CloudBees Unify workflow.

`apiVersion` and `kind`

All workflows must begin with these required metadata fields.

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow▼

Workflow configuration

Workflow-level properties set the workflow’s name, triggers, environment variables, and permissions.

`name`

Specifies the workflow name displayed in CloudBees Unify.

name: My workflow▼

`on`

Defines triggers that start workflow runs. Supported trigger types:

push: Starts the workflow based on a push request to specified branches or paths
pull_request: Starts the workflow based on a pull request and Git tags
schedule: Starts the workflow based on configured cron schedules
workflow_dispatch: Enables manual triggering via UI or API with optional input parameters
workflow_call: Enables the workflow to be called as a reusable workflow

Push trigger

The push trigger starts a workflow run when commits or tags are pushed to the repository.

on:
  push:
    branches:
      - 'main'
      - 'test/**'
    paths:
      - 'src/**'
      - '!src/docs/**'
    tags:
      - 'v*.*.*'▼

Properties:

branches: Array of branch name patterns to trigger on. Negated (!) patterns aren’t supported.
paths: Array of file path patterns to trigger on
tags: Array of tag patterns to trigger on

Wildcards in branch and path patterns: * matches any character except /; ** matches any character including /.

Pull request trigger

The pull_request trigger starts a workflow run on pull request activity.

on:
  pull_request:
    branches:
      - 'main'
      - 'develop'
    paths:
      - 'src/**'
    types:
      - opened
      - synchronize
      - reopened▼

Properties:

branches: Array of target branch patterns
paths: Array of file path patterns
types: Array of pull request activity types (opened, synchronize, reopened, closed)

Schedule trigger

The schedule trigger starts a workflow run at times set by one or more cron expressions.

on:
  schedule:
    - cron: '30 2 * * 1-5'
    - cron: '0 0 * * 0'▼

Properties:

cron: Cron expression defining the schedule (using UTC timezone)

Workflow dispatch trigger

The workflow_dispatch trigger lets you start a workflow run manually, with optional input parameters.

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deployment environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production
      version:
        description: 'Version to deploy'
        required: false
        type: string▼

Properties:

inputs: Object defining input parameters for manual triggers
inputs.<input_id>.description: Human-readable description of the input
inputs.<input_id>.required: Boolean indicating if input is required
inputs.<input_id>.default: Default value for the input
inputs.<input_id>.type: Input type (string, boolean, choice)
inputs.<input_id>.options: Array of valid options (for choice type)

Workflow call trigger

The workflow_call trigger lets another workflow call this workflow as a reusable workflow.

on:
  workflow_call:
    inputs:
      config-path:
        required: true
        type: string
    secrets:
      token:
        required: true▼

Properties:

inputs: Object defining inputs from calling workflow
secrets: Object defining secrets required from calling workflow

`env`

Sets environment variables available to all jobs in the workflow.

env:
  NODE_VERSION: '18'
  API_URL: 'https://api.example.com'
  DEBUG: 'true'▼

Environment variables can reference other environment variables and contexts using expression syntax.

env:
  DEPLOYMENT_URL: https://${{ vars.ENVIRONMENT }}.example.com
  BUILD_NUMBER: ${{ cloudbees.scm.sha }}▼

`permissions`

Configures permissions for the workflow execution context.

permissions:
  scm-token-own: read
  id-token: write▼

Available permissions:

scm-token-own: Access to the workflow’s own SCM token. Values: read (default), none.
scm-token-org: Access to the organization SCM token. Values: read, none (default).
id-token: Access to the OIDC identity token. Values: write, none (default).

Permission levels:

read: Read-only access
write: Read and write access
none: No access (explicitly deny)

Context objects

Context objects provide information about workflow runs, jobs, and the environment.

`cloudbees` context

The cloudbees context provides CloudBees Unify-specific information and is always available.

Property Type Description

Property	Type	Description
`cloudbees.api.url`	String	CloudBees Unify API endpoint URL.
`cloudbees.api.token`	String	Authentication token for CloudBees Unify API access.
`cloudbees.component.id`	String	The CloudBees Unify identifier for the component.
`cloudbees.event`	Object	The webhook payload that triggers a workflow run. `workflow_dispatch` contains the inputs and `schedule` contains the cron definition. `push` and `pull_request` contain the raw SCM payload.
`cloudbees.event_name`	String	The name of the event that triggers a workflow run: `push`, `pull_request`, `workflow_dispatch`, or `schedule`.
`cloudbees.home`	String	The home directory inside the current container; defaults to `/cloudbees/home`.
`cloudbees.org.id`	String	The CloudBees Unify identifier for the organization.
`cloudbees.registries`	String	The path to the registry mirror configuration file.
`cloudbees.run_attempt`	Number	A unique number representing each attempt of a specific workflow run.
`cloudbees.run_id`	String	A globally unique identifier assigned to each execution of a workflow.
`cloudbees.run_number`	Number	A unique, incrementing value assigned to each workflow run within a component.
`cloudbees.scm.branch`	String	The name of the repository branch that contains the workflow file.
`cloudbees.scm.provider`	String	The SCM provider. Valid values are `github`, `bitbucket`, and `bitbucket_datacenter`.
`cloudbees.scm.provider_url`	String	The SCM provider host URL; for example, `https://github.com`.
`cloudbees.scm.ref`	String	The branch or tag ref that triggers a workflow run.
`cloudbees.scm.repository`	String	The repository path in the format `<OWNER_NAME>/<REPOSITORY_NAME>`.
`cloudbees.scm.repositoryUrl`	String	The URL of the SCM repository.
`cloudbees.scm.sha`	String	Commit SHA that triggered the workflow.
`cloudbees.scm.pullRequest.number`	Number	Pull request number (pull request events only).
`cloudbees.scm.pullRequest.head.sha`	String	Head commit SHA for pull request.
`cloudbees.scm.pullRequest.base.sha`	String	Base commit SHA for pull request.
`cloudbees.scm.pullRequest.merged`	Boolean	Whether pull request is merged.
`cloudbees.scm.tag`	String	Git tag name (tag events only).
`cloudbees.scm.token`	String	The CloudBees workflow run token used to authenticate the run against CloudBees services.
`cloudbees.version`	String	A CloudBees-maintained version of a component. The patch number increments on each workflow trigger event.
`cloudbees.workspace`	String	The default working directory for platform workflows.

cloudbees.api.url

String

CloudBees Unify API endpoint URL.

cloudbees.api.token

String

Authentication token for CloudBees Unify API access.

cloudbees.component.id

String

The CloudBees Unify identifier for the component.

cloudbees.event

Object

The webhook payload that triggers a workflow run. workflow_dispatch contains the inputs and schedule contains the cron definition. push and pull_request contain the raw SCM payload.

cloudbees.event_name

String

The name of the event that triggers a workflow run: push, pull_request, workflow_dispatch, or schedule.

cloudbees.home

String

The home directory inside the current container; defaults to /cloudbees/home.

cloudbees.org.id

String

The CloudBees Unify identifier for the organization.

cloudbees.registries

String

The path to the registry mirror configuration file.

cloudbees.run_attempt

Number

A unique number representing each attempt of a specific workflow run.

cloudbees.run_id

String

A globally unique identifier assigned to each execution of a workflow.

cloudbees.run_number

Number

A unique, incrementing value assigned to each workflow run within a component.

cloudbees.scm.branch

String

The name of the repository branch that contains the workflow file.

cloudbees.scm.provider

String

The SCM provider. Valid values are github, bitbucket, and bitbucket_datacenter.

cloudbees.scm.provider_url

String

The SCM provider host URL; for example, https://github.com.

cloudbees.scm.ref

String

The branch or tag ref that triggers a workflow run.

cloudbees.scm.repository

String

The repository path in the format <OWNER_NAME>/<REPOSITORY_NAME>.

cloudbees.scm.repositoryUrl

String

The URL of the SCM repository.

cloudbees.scm.sha

String

Commit SHA that triggered the workflow.

cloudbees.scm.pullRequest.number

Number

Pull request number (pull request events only).

cloudbees.scm.pullRequest.head.sha

String

Head commit SHA for pull request.

cloudbees.scm.pullRequest.base.sha

String

Base commit SHA for pull request.

cloudbees.scm.pullRequest.merged

Boolean

Whether pull request is merged.

cloudbees.scm.tag

String

Git tag name (tag events only).

cloudbees.scm.token

String

The CloudBees workflow run token used to authenticate the run against CloudBees services.

cloudbees.version

String

A CloudBees-maintained version of a component. The patch number increments on each workflow trigger event.

cloudbees.workspace

String

The default working directory for platform workflows.

`job` context

The job context provides information about the current job.

Property Type Description

Property	Type	Description
`job.environment`	String	The evaluated environment name for the current job (the value of `jobs.<job_id>.environment` after expressions resolve).

job.environment

String

The evaluated environment name for the current job (the value of jobs.<job_id>.environment after expressions resolve).

`file` context

The file context provides information about the workflow file in which an expression appears.

Property Type Description

Property	Type	Description
`file.scm.sha`	String	The Git commit SHA of the file in which the expression appears. Use `${{ file.scm.sha }}` in `uses:` or `image:` fields to reference commit-specific container images.

file.scm.sha

String

The Git commit SHA of the file in which the expression appears. Use ${{ file.scm.sha }} in uses: or image: fields to reference commit-specific container images.

Built-in contexts

Standard contexts available in expressions:

env: Environment variables set in the workflow, job, or step
file: Provides file.scm.sha for commit-specific image tagging
inputs: Inputs for reusable workflows or manually triggered workflows
job: Information about the currently executing job
needs: Outputs from jobs that the current job depends on
outputs: Outputs set by the current job or step
secrets: Secrets available to the workflow
steps: Information about steps in the current job
vars: Custom variables defined in the workflow

Expression syntax

Expressions use ${{ }} syntax to access context properties and call functions.

Context access

Use dot notation inside an expression to read a context property.

# Access environment variable
run: echo ${{ env.NODE_VERSION }}

# Access cloudbees context
run: echo "Building commit ${{ cloudbees.scm.sha }}"

# Access job outputs
run: echo ${{ needs.build.outputs.version }}▼

Conditional expressions

Use an expression in an if property to run a job or step only when a condition is met.

# Job conditional
if: ${{ success() && env.DEPLOY_ENABLED == 'true' }}

# Step conditional
if: ${{ failure() || env.DEBUG == 'true' }}

# Multiple conditions
if: ${{ cloudbees.event_name == 'push' && startsWith(cloudbees.scm.ref, 'refs/tags/') }}▼

Functions

Status check functions:

success(): Returns true when none of the previous steps have failed or been canceled
failure(): Returns true when any previous step has failed
cancelled(): Returns true when the workflow has been canceled
always(): Returns true and causes the step to always execute (even when canceled)

String functions:

contains(search, item): Returns true if search contains item
startsWith(searchString, searchValue): Returns true if searchString starts with searchValue
endsWith(searchString, searchValue): Returns true if searchString ends with searchValue
format(string, …): Replaces placeholders in string with provided values

Differences from GitHub Actions

CloudBees Unify workflow syntax differs from GHA in some areas, including the following:

Negated branch patterns in on.push.branches: CloudBees Unify ignores negated (!) patterns in on.push.branches. A workflow that lists '!main' under branches still runs on every push to main.

Workflow syntax reference

Required metadata

apiVersion and kind

Workflow configuration

name

on

Push trigger

Pull request trigger

Schedule trigger

Workflow dispatch trigger

Workflow call trigger

env

permissions

Context objects

cloudbees context

job context

file context

Built-in contexts

Expression syntax

Context access

Conditional expressions

Functions

Differences from GitHub Actions

Related pages

`apiVersion` and `kind`

`name`

`on`

`env`

`permissions`

`cloudbees` context

`job` context

`file` context