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 DSL has the same syntax and semantics as GitHub Actions (GHA), enabling users familiar with GHA to get started quickly.
Workflow configuration
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
on: push: branches: - 'main' - 'test/**' paths: - 'src/**' - '!src/docs/**' tags: - 'v*.*.*'
Properties:
branches-
Array of branch name patterns to trigger on
paths-
Array of file path patterns to trigger on
tags-
Array of tag patterns to trigger on
Pull request trigger
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
on: schedule: - cron: '30 2 * * 1-5' - cron: '0 0 * * 0'
Properties:
cron-
Cron expression defining the schedule (using UTC timezone)
Workflow dispatch trigger
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, environment)
inputs.<input_id>.options-
Array of valid options (for choice type)
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: contents: read actions: read security-events: write
Available permissions:
actions-
Read or write access to workflow runs and artifacts
contents-
Read or write access to repository contents
deployments-
Read or write access to deployment statuses
issues-
Read or write access to issues
metadata-
Read access to repository metadata
packages-
Read or write access to packages
pages-
Read or write access to GitHub Pages
pull-requests-
Read or write access to pull requests
repository-projects-
Read or write access to repository projects
security-events-
Read or write access to security events
statuses-
Read or write access to commit statuses
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 |
|---|---|---|
|
String |
CloudBees Unify API endpoint URL |
|
String |
Authentication token for CloudBees Unify API access |
|
String |
Source control branch name |
|
String |
Repository URL |
|
String |
Commit SHA that triggered the workflow |
|
Number |
Pull request number (pull request events only) |
|
String |
Head commit SHA for pull request |
|
String |
Base commit SHA for pull request |
|
Boolean |
Whether pull request is merged |
|
String |
Git tag name (tag events only) |
|
String |
Workspace directory path |
Built-in contexts
Standard contexts available in expressions:
env-
Environment variables set in the workflow, job, or step
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
# 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
# Job conditional if: ${{ success() && env.DEPLOY_ENABLED == 'true' }} # Step conditional if: ${{ failure() || env.DEBUG == 'true' }} # Multiple conditions if: ${{ github.event_name == 'push' && startsWith(github.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